DatePicker

A composable date picker that pairs a segmented date input with a calendar popover for selecting YYYY-MM-DD dates.

Anatomy

DatePicker.Root owns the value and open state. DatePicker.Input renders locale-resolved segments, DatePicker.Trigger opens the popover, and DatePicker.Popover hosts a full calendar built from the same parts as the standalone Calendar.

<script>
	import { DatePicker } from '@human-kit/ui/datepicker';
</script>

<DatePicker.Root>
	<DatePicker.Input aria-label="Date input">
		{#snippet children(segment)}
			<DatePicker.Segment {segment} />
		{/snippet}
	</DatePicker.Input>
	<DatePicker.Trigger />

	<DatePicker.Popover>
		<DatePicker.Calendar>
			<div>
				<DatePicker.TriggerPrevious />
				<DatePicker.Heading />
				<DatePicker.TriggerNext />
			</div>
			<DatePicker.Grid>
				<DatePicker.GridHeader />
				<DatePicker.GridBody />
			</DatePicker.Grid>
		</DatePicker.Calendar>
	</DatePicker.Popover>
</DatePicker.Root>

Min and max bounds

minValue and maxValue constrain both the calendar and typed input. Out-of-range dates are never auto-corrected: the input exposes aria-invalid and data-invalid while the committed value stays null, so users can see exactly what they typed.

Usage guidelines

• Use value with onChange for controlled state and defaultValue for uncontrolled state; the empty state is null.
• Use open / defaultOpen / onOpenChange to control the popover, and closeOnSelect to keep it open after selection.
• isDateUnavailable marks specific days as non-selectable in both the input and the calendar.
• DatePicker.Popover forwards Popover.Content props such as placement (default bottom-start), offset, and shouldFlip.
• DatePicker.Calendar forwards Calendar.Root props except those controlled by the root (value, selectionMode, disabled, …).
• Wrap in a LocaleProvider to localize segment order, placeholders, and calendar labels.

Accessibility

• Segment accessible names are resolved automatically from the active locale.
• DatePicker.Input exposes aria-invalid and data-invalid when the current segment draft is not committable; invalid input is shown, never auto-corrected.
• Disabled calendar dates remain focusable via keyboard navigation so screen readers can discover and announce them as disabled.
• Popover focus defaults to the current active day cell; closing with the keyboard restores visible focus to the trigger.
• In read-only mode, the calendar trigger is hidden.

API reference

Root

The stateful container. Owns the committed date value, the popover open state, and validation shared by the input and calendar.

* required. Native HTML attributes of the underlying element are also accepted.

Input

The segmented date input. Iterates the locale-resolved segments and passes each to the children snippet.

* required. Native HTML attributes of the underlying element are also accepted.

Segment

One editable or literal segment of the date (day, month, year, or separator). Supports typing and arrow-key stepping.

* required. Native HTML attributes of the underlying element are also accepted.

Trigger

Button that opens and closes the calendar popover. Hidden in read-only mode.

* required. Native HTML attributes of the underlying element are also accepted.

Popover

The floating panel that hosts the calendar. Forwards Popover.Content props (placement, offset, shouldFlip, …); open state, trigger wiring, and id are controlled internally. Placement defaults to bottom-start and initial focus lands on the active day cell.

* required. Native HTML attributes of the underlying element are also accepted.

Calendar

The calendar surface inside the popover. Forwards Calendar.Root props except those controlled by DatePicker.Root (selectionMode, value, disabled, readonly, isDateUnavailable, …).

* required. Native HTML attributes of the underlying element are also accepted.

TriggerPrevious

Button that pages the calendar to the previous month.

* required. Native HTML attributes of the underlying element are also accepted.

Heading

Displays the visible month heading, localized through the active locale.

TriggerNext

Button that pages the calendar to the next month.

* required. Native HTML attributes of the underlying element are also accepted.

Grid

Renders the visible month as an accessible grid named after the month heading.

* required. Native HTML attributes of the underlying element are also accepted.

GridHeader

The weekday header row. Iterates the localized weekday labels and passes each to the children snippet.

* required. Native HTML attributes of the underlying element are also accepted.

HeaderCell

One weekday label cell inside the grid header row.

* required. Native HTML attributes of the underlying element are also accepted.

GridBody

The day cells area. Iterates the visible days and passes each ISO date to the children snippet.

* required. Native HTML attributes of the underlying element are also accepted.

BodyCell

One focusable day cell. Selecting it commits the date to the picker and (by default) closes the popover.

* required. Native HTML attributes of the underlying element are also accepted.