useRangeCalendar

Provides the behavior and accessibility implementation for a range calendar component. A range calendar displays one or more date grids and allows users to select a contiguous range of dates.

July 2026

S	M	T	W	T	F	S
			1	2	3	4
5	6	7	8	9	10	11
12	13	14	15	16	17	18
19	20	21	22	23	24	25
26	27	28	29	30	31

Example

RangeCalendar.tsx

RangeCalendar.css

Button.tsx

Button.css

Example

RangeCalendar.tsx

RangeCalendar.css

Button.tsx

Button.css

import {RangeCalendar} from './RangeCalendar';

<RangeCalendar aria-label="Trip dates" />

API

<RangeCalendar>
  <CalendarHeading />
  <CalendarMonthPicker />
  <CalendarYearPicker />
  <Button slot="previous" />
  <Button slot="next" />
  <CalendarGrid>
    <CalendarGridHeader>
      {day => <CalendarHeaderCell />}
    </CalendarGridHeader>
    <CalendarGridBody>
      {date => <CalendarCell date={date} />}
    </CalendarGridBody>
  </CalendarGrid>
  <Text slot="errorMessage" />
</RangeCalendar>

useRangeCalendarState<T extends DateValue = DateValue>(props: RangeCalendarStateOptions<T>): RangeCalendarState<T>

useRangeCalendar<T extends DateValue>(
  props: AriaRangeCalendarProps<T>,
state: RangeCalendarState,
ref: RefObject<FocusableElement | null>
): CalendarAria

useCalendarGrid(props: AriaCalendarGridProps, state: CalendarState<CalendarSelectionMode> | RangeCalendarState): CalendarGridAria

useCalendarCell(
  props: AriaCalendarCellProps,
state: CalendarState<CalendarSelectionMode> | RangeCalendarState,
ref: RefObject<HTMLElement | null>
): CalendarCellAria

useCalendarMonthPicker(props: CalendarMonthPickerProps, state: CalendarState<CalendarSelectionMode> | RangeCalendarState): CalendarMonthPickerAria

useCalendarYearPicker(props: CalendarYearPickerProps, state: CalendarState<CalendarSelectionMode> | RangeCalendarState): CalendarYearPickerAria

RangeCalendarState

Properties

Name	Type
`value`	`RangeValue<DateValue> \| null`
The currently selected date range.
`anchorDate`	`CalendarDate \| null`
The current anchor date that the user clicked on to begin range selection.
`highlightedRange`	`RangeValue<CalendarDate> \| null`
The currently highlighted date range.
`isDragging`	`boolean`
Whether the user is currently dragging over the calendar.
`isDisabled`	`boolean`
Whether the calendar is disabled.
`isReadOnly`	`boolean`
Whether the calendar is in a read only state.
`visibleDuration`	`DateDuration`
The visible duration in the calendar.
`visibleRange`	`RangeValue<CalendarDate>`
The date range that is currently visible in the calendar.
`timeZone`	`string`
The time zone of the dates currently being displayed.
`isValueInvalid`	`boolean`
Whether the calendar is invalid.
`focusedDate`	`CalendarDate`
The currently focused date.
`isFocused`	`boolean`
Whether focus is currently within the calendar.

Methods

`setValue(value: RangeValue<DateValue> \| null): void`
Sets the currently selected date range.
`highlightDate(date: CalendarDate): void`
Highlights the given date during selection, e.g. by hovering or dragging.
`setAnchorDate(date: CalendarDate \| null): void`
Sets the anchor date that the user clicked on to begin range selection.
`setDragging(isDragging: boolean): void`
Sets whether the user is dragging over the calendar.
`clearSelection(): void`
Clears the current selection.
`commitSelection(): void`
Commits the current selection.
`focusNearestAvailableDate(anchorDate: CalendarDate): void`
Focuses the next available day before or after the anchor date.
`setFocusedDate(value: CalendarDate): void`
Sets the focused date.
`focusNextDay(): void`
Moves focus to the next calendar date.
`focusPreviousDay(): void`
Moves focus to the previous calendar date.
`focusNextRow(): void`
Moves focus to the next row of dates, e.g. the next week.
`focusPreviousRow(): void`
Moves focus to the previous row of dates, e.g. the previous work.
`focusNextPage(): void`
Moves focus to the next page of dates, e.g. the next month if one month is visible.
`focusPreviousPage(): void`
Moves focus to the previous page of dates, e.g. the previous month if one month is visible.
`focusSectionStart(): void`
Moves focus to the start of the current section of dates, e.g. the start of the current month.
`focusSectionEnd(): void`
Moves focus to the end of the current section of dates, e.g. the end of the current month month.
`focusNextSection(larger?: boolean): void`
Moves focus to the next section of dates based on what is currently displayed. By default, focus is moved by one of the currently displayed unit. For example, if one or more months are displayed, then focus is moved forward by one month. If the `larger` option is `true`, the focus is moved by the next larger unit than the one displayed. For example, if months are displayed, then focus moves to the next year.
`focusPreviousSection(larger?: boolean): void`
Moves focus to the previous section of dates based on what is currently displayed. By default, focus is moved by one of the currently displayed unit. For example, if one or more months are displayed, then focus is moved backward by one month. If the `larger` option is `true`, the focus is moved by the next larger unit than the one displayed. For example, if months are displayed, then focus moves to the previous year.
`selectFocusedDate(): void`
Selects the currently focused date.
`selectDate(date: CalendarDate): void`
Selects the given date.
`setFocused(value: boolean): void`
Sets whether focus is currently within the calendar.
`isInvalid(date: CalendarDate): boolean`
Returns whether the given date is invalid according to the `minValue` and `maxValue` props.
`isSelected(date: CalendarDate): boolean`
Returns whether the given date is currently selected.
`isCellFocused(date: CalendarDate): boolean`
Returns whether the given date is currently focused.
`isCellDisabled(date: CalendarDate): boolean`
Returns whether the given date is disabled according to the `minValue,`maxValue`, and`isDisabled` props.
`isCellUnavailable(date: CalendarDate): boolean`
Returns whether the given date is unavailable according to the `isDateUnavailable` prop.
`isPreviousVisibleRangeInvalid(): boolean`
Returns whether the previous visible date range is allowed to be selected according to the `minValue` prop.
`isNextVisibleRangeInvalid(): boolean`
Returns whether the next visible date range is allowed to be selected according to the `maxValue` prop.
`getDatesInWeek(weekIndex: number, startDate?: CalendarDate): Array<CalendarDate \| null>`
Returns an array of dates in the week index counted from the provided start date, or the first visible date if not given. The returned array always has 7 elements, but may include null if the date does not exist according to the calendar system.
`getWeeksInMonth(startDate?: CalendarDate): number`
Returns the number of weeks in a month.

AriaRangeCalendarProps

Name	Type	Default
`commitBehavior`	`'clear' \| 'reset' \| 'select'`	Default: `'select'`
Controls the behavior when a pointer is released outside the calendar or a blur occurs mid selection: `clear`: clear the currently selected range of dates. `reset`: reset the selection to the previously selected range of dates. `select`: select the currently hovered range of dates.
`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. The second argument provides the current selection anchor date, if any. This can be used to adjust the available dates based on the user's first selected date.
`isDisabled`	`boolean`	Default: `false`
Whether the calendar is disabled.
`isReadOnly`	`boolean`	Default: `false`
Whether the calendar value is immutable.
`focusedValue`	`DateValue \| null`	Default: —
Controls the currently focused date within the calendar.
`defaultFocusedValue`	`DateValue \| null`	Default: —
The date that is focused when the calendar first mounts (uncontrolled).
`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.
`selectionAlignment`	`'start' \| 'center' \| 'end'`	Default: `'center'`
Determines the alignment of the visible months on initial render based on the current selection or current date if there is no selection.
`weeksInMonth`	`number`	Default: —
The number of weeks in a month. This overrides the default set by the locale.

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

CalendarAria

Name	Type
`calendarProps`	`DOMAttributes`
Props for the calendar grouping element.
`nextButtonProps`	`AriaButtonProps`
Props for the next button.
`prevButtonProps`	`AriaButtonProps`
Props for the previous button.
`errorMessageProps`	`DOMAttributes`
Props for the error message element, if any.
`title`	`string`
A description of the visible date range, for use in the calendar title.

AriaCalendarGridProps

Name	Type	Default
`startDate`	`CalendarDate`	Default: —
The first date displayed in the calendar grid. Defaults to the first visible date in the calendar. Override this to display multiple date grids in a calendar.
`endDate`	`CalendarDate`	Default: —
The last date displayed in the calendar grid. Defaults to the last visible date in the calendar. Override this to display multiple date grids in a calendar.
`weekdayStyle`	`'narrow' \| 'short' \| 'long'`	Default: `'narrow'`
The style of weekday names to display in the calendar grid header, e.g. single letter, abbreviation, or full day name.
`firstDayOfWeek`	`'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat'`	Default: —
The day that starts the week.

AriaCalendarCellProps

Name	Type
`date`	`CalendarDate`
The date that this cell represents.
`isDisabled`	`boolean`
Whether the cell is disabled. By default, this is determined by the Calendar's `minValue`, `maxValue`, and `isDisabled` props.
`isOutsideMonth`	`boolean`
Whether the cell is outside of the current month.

CalendarMonthPickerProps

Name	Type
`format`	`'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'`
The format of the month.

CalendarMonthPickerAria

Name	Type
`value`	`Key`

`items`	`CalendarMonthPickerItem[]`

`onChange`	`(key: Key \| null) => void`

CalendarYearPickerProps

Name	Type	Default
`visibleYears`	`number`	Default: `20`
The number of years to display.
`format`	`CalendarYearPickerFormatOptions`	Default: —
The format to display.

CalendarYearPickerAria

Name	Type
`value`	`Key`

`items`	`CalendarYearPickerItem[]`

`onChange`	`(key: Key \| null) => void`