DateRangePicker

This is a date range picker that you assemble from parts. It has two date inputs with segments: one for the start and one for the end. A range calendar goes with them, in a popover. The value is a { start, end } pair of YYYY-MM-DD strings. While the range is empty or incomplete, the value is null.

Anatomy

DateRangePicker.Root holds the range value and the open state. Two DateRangePicker.Input parts make the segments for the locale: one has part="start" and one has part="end". DateRangePicker.Popover contains a calendar in the range mode, and that calendar uses the same parts as the standalone Calendar.

<script>
	import { DateRangePicker } from '@human-kit/ui/daterangepicker';
</script>

<DateRangePicker.Root>
	<DateRangePicker.Input part="start" aria-label="Start date">
		{#snippet children(segment)}
			<DateRangePicker.Segment part="start" {segment} />
		{/snippet}
	</DateRangePicker.Input>
	<DateRangePicker.Input part="end" aria-label="End date">
		{#snippet children(segment)}
			<DateRangePicker.Segment part="end" {segment} />
		{/snippet}
	</DateRangePicker.Input>
	<DateRangePicker.Trigger />

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

Minimum and maximum

The minValue and maxValue props set the limits for the calendar and for the text that the user types. If you give no children snippet, DateRangePicker.Input makes its segments with the default styles. This demo shows that.

Usage guidelines

• When your own code controls the state, use value with onChange. When the component controls the state, use defaultValue. The value is a { start, end } pair, and the empty state is null.
• Always make one input with part="start" and one input with part="end". Give the same part value to their segments.
• Use open, defaultOpen, and onOpenChange to control the popover. Use closeOnSelect to keep the popover open after the range is complete.
• The isDateUnavailable prop makes specified days unavailable in the inputs and in the calendar.
• Set visibleMonths on DateRangePicker.Calendar to show more than one month. More than one month makes the range selection easier.
• Put the picker in a LocaleProvider to localize the sequence of the segments, the placeholders, and the names in the calendar.

Accessibility

• Give each input its own accessible name, for example aria-label="Start date" and aria-label="End date".
• The accessible name of each segment comes from the active locale.
• Each input gets aria-invalid and data-invalid when its 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.
• In the range calendar, the first selection starts the range. The arrow keys make the range longer or shorter. The Enter key and the Space key complete the range.

API reference

Root

The container with the state. It holds the { start, end } range value, the open state of the popover, and the validation. The two inputs and the calendar share them.

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

Input

One date input with segments, for one end of the range. Make one with part="start" and one with part="end". If you give no children snippet, the segments get the default styles.

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

Segment

One segment of one end of the range: 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 range calendar popover.

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

Popover

The panel that floats and contains the range 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.

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

Calendar

The calendar in the popover, always in the range mode. It accepts Calendar.Root props, for example visibleMonths. It does not accept the props that DateRangePicker.Root controls.

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

TriggerPrevious

The button that moves the calendar to the previous month, or to the previous set of months.

* 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, or to the next set of months.

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

Grid

Makes one 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. The first selection starts the range. While the pointer moves, the calendar shows the range. The second selection completes it.

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