useDateRangePicker

Provides the behavior and accessibility implementation for a date picker component. A date range picker combines two DateFields and a RangeCalendar popover to allow users to enter or select a date and time range.

Trip dates

mmddyyyy

Example

DateRangePicker.tsx

DateRangePicker.css

DateField.css

RangeCalendar.css

Button.css

Form.css

Popover.css

Example

DateRangePicker.tsx

DateRangePicker.css

DateField.css

RangeCalendar.css

Button.css

Form.css

Popover.css

import {DateRangePicker} from './DateRangePicker';

<DateRangePicker label="Trip dates" />

API

<DateRangePicker>
  <Label />
  <Group>
    <DateInput slot="start">
      {segment => <DateSegment segment={segment} />}
    </DateInput>
    <span aria-hidden="true">–</span>
    <DateInput slot="end">
      {segment => <DateSegment segment={segment} />}
    </DateInput>
    <Button />
  </Group>
  <Popover>
    <RangeCalendar />
  </Popover>
</DateRangePicker>

useDateRangePickerState<T extends DateValue = DateValue>(props: DateRangePickerStateOptions<T>): DateRangePickerState

useDateRangePicker<T extends DateValue>(
  props: AriaDateRangePickerProps<T>,
state: DateRangePickerState,
ref: RefObject<Element | null>
): DateRangePickerAria

DateRangePickerState

Properties

Name	Type
`dateRange`	`RangeValue<DateValue \| null> \| null`
The date portion of the selected range. This may be set prior to `value` if the user has selected a date range but has not yet selected a time range.
`timeRange`	`RangeValue<TimeValue \| null> \| null`
The time portion of the selected range. This may be set prior to `value` if the user has selected a time range but has not yet selected a date range.
`granularity`	`Granularity`
The granularity for the field, based on the `granularity` prop and current value.
`hasTime`	`boolean`
Whether the date range picker supports selecting times, according to the `granularity` prop and current value.
`point`	`Point \| null`
The cursor position when the overlay was triggered, relative to the window viewport.
`realtimeValidation`	`ValidationResult`
Realtime validation results, updated as the user edits the value.
`displayValidation`	`ValidationResult`
Currently displayed validation results, updated when the user commits their changes.

`value`	`RangeValue<DateValue \| null>`
The currently selected date range.
`defaultValue`	`DateRange \| null`
The default selected date range.

Methods

`setValue(value: DateRange \| null): void`
Sets the selected date range.
`setDateRange(value: DateRange): void`
Sets the date portion of the selected range.
`setTimeRange(value: TimeRange): void`
Sets the time portion of the selected range.
`setDate(part: 'start' \| 'end', value: DateValue \| null): void`
Sets the date portion of either the start or end of the selected range.
`setTime(part: 'start' \| 'end', value: TimeValue \| null): void`
Sets the time portion of either the start or end of the selected range.
`setDateTime(part: 'start' \| 'end', value: DateValue \| null): void`
Sets the date and time of either the start or end of the selected range.
`setOpen(isOpen: boolean): void`
Sets whether the calendar popover is open.
`formatValue(locale: string, fieldOptions: FieldOptions): {start: string, end: string } \| null`
Formats the selected range using the given options.
`getDateFormatter(locale: string, formatOptions: FormatterOptions): DateFormatter`
Gets a formatter based on state's props.
`open(): void`
Opens the overlay.
`close(): void`
Closes the overlay.
`toggle(): void`
Toggles the overlay's visibility.
`setPoint(point: Point): void`
Sets the cursor position relative to the window viewport.
`updateValidation(result: ValidationResult): void`
Updates the current validation result. Not displayed to the user until `commitValidation` is called.
`resetValidation(): void`
Resets the displayed validation state to valid when the user resets the form.
`commitValidation(): void`
Commits the realtime validation so it is displayed to the user.

AriaDateRangePickerProps

Name	Type	Default
`allowsNonContiguousRanges`	`boolean`	Default: —
When combined with `isDateUnavailable`, determines whether non-contiguous ranges, i.e. ranges containing unavailable dates, may be selected.
`isDateUnavailable`	`(date: DateValue, anchorDate: CalendarDate \| null) => boolean`	Default: —
Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
`pageBehavior`	`PageBehavior`	Default: `visible`
Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
`firstDayOfWeek`	`'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat'`	Default: —
The day that starts the week.
`placeholderValue`	`DateValue \| null`	Default: —
A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to today's date at midnight.
`hourCycle`	`12 \| 24`	Default: —
Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
`granularity`	`Granularity`	Default: —
Determines the smallest unit that is displayed in the date picker. By default, this is `"day"` for dates, and `"minute"` for times.
`hideTimeZone`	`boolean`	Default: `false`
Whether to hide the time zone abbreviation.
`shouldForceLeadingZeros`	`boolean`	Default: —
Whether to always show leading zeros in the month, day, and hour fields. By default, this is determined by the user's locale.
`isDisabled`	`boolean`	Default: —
Whether the input is disabled.
`isReadOnly`	`boolean`	Default: —
Whether the input can be selected but not changed by the user.

`value`	`RangeValue<DateValue> \| null`	Default: —
The current value (controlled).
`defaultValue`	`RangeValue<DateValue> \| null`	Default: —
The default value (uncontrolled).
`onChange`	`(value: RangeValue<MappedDateValue<DateValue>> \| null) => void`	Default: —
Handler that is called when the value changes.

DateRangePickerAria

Name	Type
`labelProps`	`DOMAttributes`
Props for the date range picker's visible label element, if any.
`groupProps`
Props for the grouping element containing the date fields and button.
`startFieldProps`	`<DateValue>`
Props for the start date field.
`endFieldProps`	`<DateValue>`
Props for the end date field.
`buttonProps`	`AriaButtonProps`
Props for the popover trigger button.
`descriptionProps`	`DOMAttributes`
Props for the description element, if any.
`errorMessageProps`	`DOMAttributes`
Props for the error message element, if any.
`dialogProps`	`AriaDialogProps`
Props for the popover dialog.
`calendarProps`	`RangeCalendarProps<DateValue>`
Props for the range calendar within the popover dialog.
`validationDetails`	`ValidityState`
The native validation details for the input.