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	string | { start?: string; end?: string } | null	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.
showActions	boolean	false	—	Shows the panel Clear / Submit row. When false, valid selections commit automatically.
open	boolean	—	—	Controlled panel state. Use with update:open.

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 label text when the label slot is empty.
startLabel	string	""	—	Range mode: label above the start trigger. Defaults to locale From.
endLabel	string	""	—	Range mode: label above the end trigger. Defaults to locale To.
placeholder	string	""	—	Placeholder for the typed date value. In range mode, applies to the start trigger only; the end trigger uses a lowercased display-format hint.
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.
showClearButton	boolean	false	—	Shows an inline reset icon inside the trigger, immediately before the calendar icon.
clearButtonAriaLabel	string	""	—	Accessible label for the inline reset icon; defaults to bundled inputDate.clear.
supportingText	string | string[] | { text, intent?, icon? } | { text, intent?, icon? }[]	""	—	Message(s) below the field. See Inputs overview — Multiple supporting messages.
size	string	"m"	s, m, l	Dimensions and typography.
intent	string	"neutral"	neutral, warning, danger, success	Status styling; danger sets aria-invalid.
disabled	boolean	false	—	Disables the trigger, calendar button, 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.

Advanced

Prop	Type	Default	Options	Description
id	string	""	—	DOM id for the input. Auto-generated when omitted.
name	string	""	—	Native name for form submission. Range mode submits start/end controls as ${name}-start and ${name}-end.
autofocus	boolean	false	—	Autofocus on the first text input.
optional	boolean	false	—	Shows optional hint on the label when not required.
optionalText	string	""	—	Overrides optional hint text.
info	string	""	—	Info tooltip on the label.
alignment	string	"left"	left, center, right	Label alignment.
requiredMarker	string	"*"	—	Visual required marker.
requiredScreenReaderText	string	""	—	Supplemental screen-reader text for required fields.
testSelectors	object	See Test Selectors	—	Overrides for data-test.

Values

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

Display formats affect only the text shown in the input controls. Model values, events, constraints, and form serialization continue to use the canonical value formats above.

Events

Name	Payload	Description
update:modelValue	string | { start?: string; end?: string } | null	Committed value changed.
update:open	boolean	Panel open state changed.
submit	string | { start?: string; end?: string }	Draft value submitted from the panel action row when showActions is true.
clear	—	Clear action 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 the year grid, arrow keys move between years, PageUp / PageDown move between year ranges, and Enter / Space selects the active year.

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	Range mode: custom label above the start trigger; falls back to startLabel prop / locale.
endLabel	Range mode: custom label above the end trigger; falls back to endLabel prop / locale.

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; the visible range text inputs also use ${name}-start and ${name}-end for progressive form compatibility.

Test selectors

Attribute	Default	Applies to
root	catnip-input-date	Field wrapper
control	catnip-input-date-control	Single-date text input
startControl	catnip-input-date-start-control	Range start text input
endControl	catnip-input-date-end-control	Range end text input
startLabel	catnip-input-date-start-label	Range start segment label
endLabel	catnip-input-date-end-label	Range end segment label
clearButton	catnip-input-date-clear	Single-date inline reset button
startClearButton	catnip-input-date-start-clear	Range start inline reset button
endClearButton	catnip-input-date-end-clear	Range end inline reset button
singleCalendarButton	catnip-input-date-calendar-button	Single-date calendar trigger button
startCalendarButton	catnip-input-date-start-calendar-button	Range start calendar trigger button
endCalendarButton	catnip-input-date-end-calendar-button	Range end calendar trigger button
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
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
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
actionClearButton	catnip-input-date-action-clear	Panel Clear action button
actionSubmitButton	catnip-input-date-action-submit	Panel Submit action button
supportingText	catnip-input-date-supporting-text	Supporting message