useCalendar

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

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

Calendar.tsx

Calendar.css

Button.tsx

Button.css

Example

Calendar.tsx

Calendar.css

Button.tsx

Button.css

import {Calendar} from './Calendar';

<Calendar aria-label="Event date" />

API

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

useCalendarState<T extends DateValue = DateValue, M extends CalendarSelectionMode = 'single'>(props: CalendarStateOptions<T, M>): CalendarState<M>

useCalendar<T extends DateValue, M extends CalendarSelectionMode = 'single'>(props: AriaCalendarProps<T, M>, state: CalendarState<M>): 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

CalendarState

Properties

Name	Type
`value`	`CalendarValueType<CalendarDate \| null, CalendarSelectionMode>`
The currently selected date.
`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.

`selectionMode`	`CalendarSelectionMode`
Whether single or multiple selection is enabled.

Methods

`setValue(value: CalendarValueType<CalendarDate \| null, CalendarSelectionMode>): void`
Sets the currently selected 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.

AriaCalendarProps

Name	Type	Default
`isDateUnavailable`	`(date: DateValue) => boolean`	Default: —
Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
`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.

`selectionMode`	`CalendarSelectionMode`	Default: `'single'`
Whether single or multiple selection is enabled.

`value`	`CalendarValueType<DateValue \| null, CalendarSelectionMode>`	Default: —
The current value (controlled).
`defaultValue`	`CalendarValueType<DateValue \| null, CalendarSelectionMode>`	Default: —
The default value (uncontrolled).
`onChange`	`(value: CalendarValueType<MappedDateValue<DateValue>, CalendarSelectionMode>) => 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.

CalendarGridAria

Name	Type
`gridProps`	`DOMAttributes`
Props for the date grid element (e.g. `<table>`).
`headerProps`	`DOMAttributes`
Props for the grid header element (e.g. `<thead>`).
`weekDays`	`string[]`
A list of week day abbreviations formatted for the current locale, typically used in column headers.
`weeksInMonth`	`number`
The number of weeks in the month.

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.

CalendarCellAria

Name	Type
`cellProps`	`DOMAttributes`
Props for the grid cell element (e.g. `<td>`).
`buttonProps`	`DOMAttributes`
Props for the button element within the cell.
`isPressed`	`boolean`
Whether the cell is currently being pressed.
`isSelected`	`boolean`
Whether the cell is selected.
`isFocused`	`boolean`
Whether the cell is focused.
`isDisabled`	`boolean`
Whether the cell is disabled, according to the calendar's `minValue`, `maxValue`, and `isDisabled` props. Disabled dates are not focusable, and cannot be selected by the user. They are typically displayed with a dimmed appearance.
`isUnavailable`	`boolean`
Whether the cell is unavailable, according to the calendar's `isDateUnavailable` prop. Unavailable dates remain focusable, but cannot be selected by the user. They should be displayed with a visual affordance to indicate they are unavailable, such as a different color or a strikethrough. Note that because they are focusable, unavailable dates must meet a 4.5:1 color contrast ratio, as defined by WCAG.
`isOutsideVisibleRange`	`boolean`
Whether the cell is outside the visible range of the calendar. For example, dates before the first day of a month in the same week.
`formattedDate`	`string`
The day number formatted according to the current locale.

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`