Date Input

Shared label and supporting-text behaviour with catnip-input is summarised on Inputs overview.

catnip-input-date

Props

Value & mode

Prop	Type	Default	Options	Description
modelValue	CatnipInputDateModelValue	null	—	Committed value; model-value in HTML / .modelValue in frameworks.
mode	string	"single"	single, range	Single date/datetime or range selection.
showTime	boolean	false	—	Adds a time input and serializes endpoints as YYYY-MM-DDTHH:mm. Shows the panel action footer.
showPresets	boolean	false	—	Range-only. Shows the preset sidebar (Today, Last 7 days, Custom range, …). Ignored in single mode.
periodPresets	CatnipInputDatePeriodPresetConfig[]	[]	Built-in preset ids	Subset, reorder, or relabel built-in range presets. Empty uses the full built-in list.
showActions	boolean	false	—	Forces the panel Reset / Cancel / Apply row. Also shown automatically for showTime and showPresets.
open	boolean	—	—	Controlled panel state. Pair with open-change.

Date constraints

Prop	Type	Default	Options	Description
min	string	""	YYYY-MM-DD	Earliest selectable date.
max	string	""	YYYY-MM-DD	Latest selectable date.
disabledDates	string[]	[]	YYYY-MM-DD values	Specific disabled days.
maxRangeDays	number	—	Positive integer	Range-only inclusive maximum number of calendar days. 0 / unset means no range-length limit.
firstDayOfWeek	number	1	0 through 6	First day in the calendar grid; 0 is Sunday, 1 is Monday.
locale	string	""	BCP 47 locale	Locale for month and weekday labels. Empty uses the browser locale.

Field presentation

Prop	Type	Default	Options	Description
label	string	""	—	Visible field label when the label slot is empty.
startLabel	string	""	—	Vertical range+time panel: From field label. Defaults to locale From.
endLabel	string	""	—	Vertical range+time panel: To field label. Defaults to locale To.
placeholder	string	""	—	Placeholder for the combined trigger. Empty uses the active display format (YYYY-MM-DD — YYYY-MM-DD in range mode).
displayFormat	string	"YYYY-MM-DD"	Day.js format tokens	Visible date-only input format. Parsing also accepts this format; emitted values stay canonical.
displayDateTimeFormat	string	"YYYY-MM-DD, HH:mm"	Day.js format tokens	Visible datetime input format when the typed value includes time. Parsing also accepts this format; emitted values stay canonical.
panelOrientation	"horizontal" | "vertical"	"horizontal"	horizontal, vertical	Horizontal pages one month (two side-by-side in range). Vertical stacks a scrollable month list. Range horizontal switches to vertical automatically below 800px.
panelPlacement	"top" | "bottom"	"bottom"	top, bottom	Preferred panel placement. Flips when there is insufficient space.
panelAlign	"start" | "end"	"start"	start, end	Cross-axis alignment of the panel relative to the trigger.
showClearButton	boolean	true	—	Shows an inline reset icon inside the trigger when the field has a value.
clearButtonAriaLabel	string	""	—	Accessible label for the inline reset icon; defaults to bundled inputDate.clear.
supportingText	SupportingTextProp	""	—	One or more helper or validation messages. Each object requires text; intent accepts neutral, danger, warning, or success, and icon accepts a Catnip icon name. See supporting-text examples.
size	"s" | "m" | "l"	"m"	s, m, l	Dimensions and typography.
intent	"neutral" | "danger" | "warning" | "success"	"neutral"	neutral, danger, warning, success	Semantic state applied to field and supporting-text styling; danger sets aria-invalid on the date control.
disabled	boolean	false	—	Disables the trigger, calendar, and panel actions.
readonly	boolean	false	—	Prevents editing and panel interaction.
required	boolean	false	—	Native required state and label marker.
hideLabel	boolean	false	—	Hides the built-in label row.
ariaLabel	string	""	—	aria-label when there is no visible label.
ariaDescribedby	string	""	—	Extra id values merged into aria-describedby alongside generated supporting-text ids.

Advanced

Prop	Type	Default	Options	Description
id	string	""	—	DOM id for the input. Auto-generated when omitted.
name	string	""	—	Native name for form submission.
autofocus	boolean	false	—	Autofocus on the text input.
optional	boolean	false	—	When true and not required, shows the localized optional hint.
optionalText	string	""	—	Overrides the localized optional hint (HTML: optional-text).
info	string	""	—	Info tooltip beside the label; when non-empty, it wins over the label.suffix slot.
alignment	"left" | "center" | "right"	"left"	left, center, right	Horizontal alignment of the field label block.
requiredMarker	string	"*"	—	Visual marker for required fields (HTML: required-marker).
requiredScreenReaderText	string	""	—	Optional screen-reader supplement; it does not replace required on the control (HTML: required-screen-reader-text).
testSelectors	TestSelectorsProp	See Test Selectors	—	Overrides stable data-test values.

Values

Mode	show-time	show-presets	Value
Single	false	—	"YYYY-MM-DD"
Single	true	—	"YYYY-MM-DDTHH:mm"
Range	false	false	{ start?: "YYYY-MM-DD"; end?: "YYYY-MM-DD" }
Range	true	false	{ start?: "YYYY-MM-DDTHH:mm"; end?: "YYYY-MM-DDTHH:mm" }
Range	—	true	{ start?: string; end?: string; preset?: string }

Built-in preset ids: today, yesterday, last-7-days, last-30-days, last-90-days, this-month, last-month, all-time, custom.

Display formats affect only the text shown in the input. Model values, events, constraints, and form serialization continue to use the canonical value formats above. Range endpoints in the trigger are separated with an em dash (—). The trigger fills its container; when the value does not fit on one line it wraps and the field grows in height.

Events

Name	Payload	Description
update:modelValue	string | { start?: string; end?: string; preset?: string } | null	Committed value changed.
open-change	boolean	Panel open state changed (true / false). Use @open-change.
submit	string | { start?: string; end?: string; preset?: string }	Draft value applied from the panel action row.
cancel	—	Cancel discarded the draft and closed the panel.
clear	—	Reset or inline clear reset the value.
close	—	Panel dismissed.

Keyboard

Key	Behaviour
Arrow Left / Right	Move active day backward / forward.
Arrow Up / Down	Move active day by one week.
Home / End	Move to the start / end of the active week.
PageUp / PageDown	Move to the previous / next month.
Shift + PageUp / Shift + PageDown	Move to the same month in the previous / next year.
Enter / Space	Select active date.
Escape	Close the panel.

The month/year header button opens a year grid. In range mode it also opens a month grid: years on the left and months on the right in the horizontal dual-month panel, or years above months in the vertical stack. Selecting a year updates the month grid; selecting a month returns to the day calendars. Single-date mode still uses the year grid only. In the year grid, arrow keys move between years, PageUp / PageDown move between year ranges, and Enter / Space selects the active year. In the month grid, arrows move between months and Enter / Space selects the active month.

Slots

Name	Description
label	Custom label content; falls back to label prop.
label.action	Trailing action in the label row.
label.suffix	Custom label suffix; used only when info is empty.
startLabel	Vertical range+time panel: custom From label; falls back to startLabel prop / locale.
endLabel	Vertical range+time panel: custom To label; falls back to endLabel prop / locale.
value	Selected-value area inside the default trigger (calendar icon, clear, and chevron stay). Replaces the typeable field.
trigger	Full trigger override — see Trigger slot below.

Trigger slot

When trigger is set, the default field shell is replaced. The slot is wrapped in an anchor used to position the calendar panel.

• Include a focusable control (e.g. <button type="button">). Date applies aria-haspopup="grid", aria-expanded, and aria-controls.
• Click and Enter / Space toggle open/close; ArrowDown opens and moves into the calendar.
• Prefer the value slot when you only need to customize the selected-date display.
• If both are set, trigger wins and value is ignored.

Forms

The name you set on <catnip-input-date> participates in form serialization. Single mode submits the committed string value. Range mode serializes the committed object as JSON for form-associated custom element submission.

Test selectors

Attribute	Default	Applies to
root	catnip-input-date	Field wrapper
control	catnip-input-date-control	Combined wrapping text control
value	catnip-input-date-value	Custom value slot mount
clearButton	catnip-input-date-clear	Inline reset button
chevron	catnip-input-date-chevron	Trailing open/close chevron
previousButton	catnip-input-date-previous	Previous month / year-range button
nextButton	catnip-input-date-next	Next month / year-range button
viewToggle	catnip-input-date-view-toggle	Month/year header toggle
panel	catnip-input-date-panel	Floating calendar panel
presets	catnip-input-date-presets	Range preset list
preset	catnip-input-date-preset	Range preset row
month	catnip-input-date-month	Month block in the panel
grid	catnip-input-date-grid	Calendar grid
day	catnip-input-date-day	Calendar day button
yearGrid	catnip-input-date-year-grid	Year selection grid
year	catnip-input-date-year	Year selection button
monthGrid	catnip-input-date-month-grid	Range month selection grid
monthName	catnip-input-date-month-name	Range month selection button
time	catnip-input-date-time	Optional time section
singleTimeInput	catnip-input-date-time-input	Single-date time input
startTimeInput	catnip-input-date-start-time-input	Range start time input
endTimeInput	catnip-input-date-end-time-input	Range end time input
startLabel	catnip-input-date-start-label	Vertical range+time From label
endLabel	catnip-input-date-end-label	Vertical range+time To label
actionResetButton	catnip-input-date-action-reset	Panel Reset action button
actionCancelButton	catnip-input-date-action-cancel	Panel Cancel action button
actionSubmitButton	catnip-input-date-action-submit	Panel Apply action button
supportingText	catnip-input-date-supporting-text	Supporting message