DatePicker

This is a date picker that you assemble from parts. It puts a date input with segments together with a calendar in a popover. The user selects a date in the format YYYY-MM-DD.

Anatomy

DatePicker.Root holds the value and the open state. DatePicker.Input makes the segments for the locale. DatePicker.Trigger opens the popover. DatePicker.Popover contains a full calendar, and that calendar uses 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>

Minimum and maximum

The minValue and maxValue props set the limits for the calendar and for the text that the user types. The component never corrects a date that is out of the limits. The input gets aria-invalid and data-invalid, and the value stays null. Thus the user sees the exact text that the user typed.

Usage guidelines

• When your own code controls the state, use value with onChange. When the component controls the state, use defaultValue. The empty state is null.
• Use open, defaultOpen, and onOpenChange to control the popover. Use closeOnSelect to keep the popover open after a selection.
• The isDateUnavailable prop makes specified days unavailable in the input and in the calendar.
• DatePicker.Popover accepts the props of Popover.Content, for example placement (the default is bottom-start), offset, and shouldFlip.
• DatePicker.Calendar accepts the props of Calendar.Root. It does not accept the props that the root controls, for example value, selectionMode, and disabled.
• Put the picker in a LocaleProvider to localize the sequence of the segments, the placeholders, and the names in the calendar.

Accessibility

• The accessible name of each segment comes from the active locale.
• DatePicker.Input gets aria-invalid and data-invalid when the segments do not make a valid date. The component shows the text of the user, and it never corrects the text.
• A disabled date in the calendar keeps the focus. Thus a screen reader can find it and announce it as disabled.
• When the popover opens, the focus goes to the day cell of the current date. If the user closes the popover with the keyboard, the focus goes back to the trigger.
• In the read-only mode, the calendar trigger is not in the DOM.

API reference

Root

The container with the state. It holds the date value, the open state of the popover, and the validation. The input and the calendar share them.

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

Input

The date input with segments. It goes through the segments of the locale and gives each one to the children snippet.

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

Segment

One segment of the date: the day, the month, the year, or a separator. The user can type in it, and the arrow keys change its value.

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

Trigger

The button that opens and closes the calendar popover. In the read-only mode, it is not in the DOM.

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

Popover

The panel that floats and contains the calendar. It accepts Popover.Content props, for example placement, offset, and shouldFlip. The component controls the open state, the reference to the trigger, and the id. The default placement is bottom-start, and the focus goes first to the active day cell.

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

Calendar

The calendar in the popover. It accepts Calendar.Root props. It does not accept the props that DatePicker.Root controls, for example selectionMode, value, disabled, readonly, and isDateUnavailable.

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

TriggerPrevious

The button that moves the calendar to the previous month.

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

Heading

Shows the heading of the month, in the language of the active locale.

TriggerNext

The button that moves the calendar to the next month.

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

Grid

Makes the month into an accessible grid. The month heading gives the grid its name.

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

GridHeader

The header row of the weekdays. It goes through the localized weekday names and gives each one to the children snippet.

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

HeaderCell

One cell with a weekday name, in the header row of the grid.

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

GridBody

The area of the day cells. It goes through the days that the user sees and gives each ISO date to the children snippet.

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

BodyCell

One day cell that can take the focus. When the user selects it, the picker takes the date. By default, the popover then closes.

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