Date Input

Use catnip-input-date when users need a calendar-backed date field, optional time selection, or a start/end date range. 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. Add show-actions when users should explicitly confirm date/time changes.
• Range: Use mode="range" for start/end workflows such as travel dates, reporting windows, and eligibility periods. Each trigger shows a From / To segment label (override with start-label / end-label or startLabel / endLabel slots). An optional group label adds context above both (e.g. "Trip dates"). Default range selection emits after the end date is selected. Add show-actions when users need to review both endpoints before emitting.
• Clear: The panel Clear / Submit row is hidden by default; opt in with show-actions. Set show-clear-button to show a reset icon inside each trigger. Clearing single mode emits null; clearing a range trigger emits the remaining range object with that endpoint empty.
• 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 for optional group context; startLabel / endLabel props or slots label each range trigger (From / To by default). label.action / label.suffix match Input on the group label only.
• 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.
• 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 for speed.
• Let users change distant years from the month/year header instead of repeatedly stepping month by month. Keyboard users can use Shift + PageUp / Shift + PageDown from the day grid.