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; picking days in the calendar switches to Custom range. 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. Give the field the width you can spare: the combined value stays on one line when it fits, and wraps (growing the trigger) when it does not. 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.

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 / Enter / Space toggle the panel. 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.
• 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.