Date Input

Use catnip-input-date when users need a calendar-backed date field, optional time selection, a start/end date range, or a range with named presets. For free-form text, use Input. For numeric values, use Number Input.

Behaviour

• Single date: Use the default mode="single" for one date. Calendar clicks emit immediately when show-time is off; valid typed values commit on Enter or blur.
• Date and time: Add show-time when a time matters. Values serialize as YYYY-MM-DDTHH:mm. The panel keeps a draft until Apply; Cancel discards it and Reset clears the draft.
• Range: Use mode="range" for start/end workflows such as travel dates, reporting windows, and eligibility periods. One combined trigger shows both endpoints. Default date-only range selection emits after the end date is selected.
• Presets: Add show-presets on range mode for rolling windows (Today, Last 30 days, This month, and so on). Named presets display their label in the trigger and their dates while the field has focus, so people can check or adjust them; editing the dates, or picking days in the calendar, switches to Custom range. All time keeps its label. Preset selection stays in draft until Apply.
• Layout: panel-orientation="horizontal" pages months (two months for range). Below 800px, range horizontal panels use the stacked vertical layout instead. vertical is always a stacked, scrollable month list. panel-placement and panel-align control where the panel opens relative to the trigger; it still flips when space is tight. When the field shows supporting text, the panel opens below it so error messages stay visible. Give the field the width you can spare: the value stays on one line and scrolls inside the field when it doesn't fit. A date-time range needs about 400px to show in full. With show-presets, the preset list is a full-height left column; Reset / Cancel / Apply sit under the calendars only.
• Clear: The inline clear control is shown by default when the field has a value. The panel Reset / Cancel / Apply row appears for show-time, show-presets, or an explicit show-actions. Clearing single mode emits null; clearing a range emits an empty range object.
• Typing: Accept and store canonical strings. Use display-format for visible text layouts and placeholders such as DD/MM/YYYY only as hints; do not rely on placeholder text instead of a visible label. The field announces its format to screen readers, and also accepts other separators, missing leading zeros, digits without separators, and month names (useful for voice input), rewriting the date in the display format on blur. Text that doesn't parse stays in the field and is flagged on blur with a format message instead of being reverted or committed. Time boxes accept only digits and :, and expand shorthand such as 930 to 09:30. On phones, a single date with an all-digit display-format brings up a number pad.
• Opening: The calendar opens on click or Arrow Down, never on focus alone, so keyboard users tabbing through a form aren't interrupted by a panel covering the next fields. Tab from the field closes it.

Constraints

• Bounds: Set min and max when users must stay inside a known window.
• Disabled dates: Use disabled-dates for specific unavailable days, e.g. holidays or maintenance windows.
• Range length: Use max-range-days to cap range selections by inclusive calendar days, e.g. max-range-days="7" allows the start date plus the next six days.
• Week start: Use first-day-of-week to match regional expectations. The default is 1 (Monday).
• Locale: Set locale for month and weekday labels when the app locale differs from the browser context.

Composition

• Labels: label prop or label slot above the single trigger. startLabel / endLabel props or slots label the From / To datetime fields in the vertical range+time panel. label.action / label.suffix match Input on the group label only.
• Custom value: slot="value" replaces the typeable date text inside the default trigger (icon, clear, and chevron remain). The field is no longer typed — selection still goes through the calendar.
• Custom trigger: slot="trigger" replaces the whole field shell. Include a focusable control; click toggles the panel, and Enter / Space / Arrow Down open it with focus inside. Use this only when you need a non-field control (e.g. a button).
• Supporting text: Pass supporting-text on the host. Do not mount FieldSupportingText manually.
• Status: intent follows the shared field model: neutral, warning, danger, and success.

Best practices

• Prefer date-only mode unless the user truly needs a time.
• Use range mode only when both endpoints belong to the same decision.
• Use show-presets for reporting windows and similar “last N days” choices; keep plain range when the user is picking two specific dates.
• Match the display format to the product locale or workflow while keeping submitted values canonical for APIs and storage.
• Keep disabled dates explainable in nearby supporting text when the reason is not obvious. Screen reader users hear them as unavailable, but not why.
• Avoid forcing users to open the calendar for known dates; the field remains typeable unless you use slot="value" or slot="trigger".
• Let users jump by month and year from the header instead of repeatedly stepping month by month. In range mode the header shows years and months together. Keyboard users can also use Shift + PageUp / Shift + PageDown from the day grid.