useCalendarState

Provides state management for a calendar component. A calendar displays one or more date grids and allows users to select a single date.

install	`yarn add react-stately`
version	3.32.2
usage	`import {useCalendarState} from 'react-stately'`

View repository

GitHub

View package

NPM

API#

useCalendarState<T extends DateValue = DateValue>(
  (props: CalendarStateOptions<T>
)): CalendarState

Interface#

Properties

Name	Type	Description
`value`	`CalendarDate \| null`	The currently selected date.
`isDisabled`	`boolean`	Whether the calendar is disabled.
`isReadOnly`	`boolean`	Whether the calendar is in a read only state.
`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.
`minValue`	`DateValue \| null`	The minimum allowed date that a user may select.
`maxValue`	`DateValue \| null`	The maximum allowed date that a user may select.

Methods

Method	Description
`setValue( (value: CalendarDate \| \| null )): 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.

Example#

See the docs for useCalendar in react-aria for an example of useCalendarState.

CalendarDate
  | CalendarDateTime
  | ZonedDateTime

A CalendarDate represents a date without any time components in a specific calendar system.

Properties

Name	Type	Description
`calendar`	`Calendar`	The calendar system associated with this date, e.g. Gregorian.
`era`	`string`	The calendar era for this date, e.g. "BC" or "AD".
`year`	`number`	The year of this date within the era.
`month`	`number`	The month number within the year. Note that some calendar systems such as Hebrew may have a variable number of months per year. Therefore, month numbers may not always correspond to the same month names in different years.
`day`	`number`	The day number within the month.

Methods

Method	Description
`constructor( (...args: any[] )): void`
`copy(): CalendarDate`	Returns a copy of this date.
`add( (duration: DateDuration )): CalendarDate`	Returns a new `CalendarDate` with the given duration added to it.
`subtract( (duration: DateDuration )): CalendarDate`	Returns a new `CalendarDate` with the given duration subtracted from it.
`set( (fields: DateFields )): CalendarDate`	Returns a new `CalendarDate` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: DateField, amount: number, options?: CycleOptions ): CalendarDate`	Returns a new `CalendarDate` with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.
`toDate( (timeZone: string )): Date`	Converts the date to a native JavaScript Date object, with the time set to midnight in the given time zone.
`toString(): string`	Converts the date to an ISO 8601 formatted string.
`compare( (b: AnyCalendarDate )): number`	Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after.

A CalendarDateTime represents a date and time without a time zone, in a specific calendar system.

Properties

Name	Type	Description
`calendar`	`Calendar`	The calendar system associated with this date, e.g. Gregorian.
`era`	`string`	The calendar era for this date, e.g. "BC" or "AD".
`year`	`number`	The year of this date within the era.
`month`	`number`	The month number within the year. Note that some calendar systems such as Hebrew may have a variable number of months per year. Therefore, month numbers may not always correspond to the same month names in different years.
`day`	`number`	The day number within the month.
`hour`	`number`	The hour in the day, numbered from 0 to 23.
`minute`	`number`	The minute in the hour.
`second`	`number`	The second in the minute.
`millisecond`	`number`	The millisecond in the second.

Methods

Method	Description
`constructor( (...args: any[] )): void`
`copy(): CalendarDateTime`	Returns a copy of this date.
`add( (duration: DateTimeDuration )): CalendarDateTime`	Returns a new `CalendarDateTime` with the given duration added to it.
`subtract( (duration: DateTimeDuration )): CalendarDateTime`	Returns a new `CalendarDateTime` with the given duration subtracted from it.
`set( (fields: DateFields & & TimeFields )): CalendarDateTime`	Returns a new `CalendarDateTime` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: DateField \| \| TimeField, amount: number, options?: CycleTimeOptions ): CalendarDateTime`	Returns a new `CalendarDateTime` with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.
`toDate( (timeZone: string, , disambiguation?: Disambiguation )): Date`	Converts the date to a native JavaScript Date object in the given time zone.
`toString(): string`	Converts the date to an ISO 8601 formatted string.
`compare( (b: CalendarDate \| CalendarDateTime \| ZonedDateTime )): number`	Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after.

A ZonedDateTime represents a date and time in a specific time zone and calendar system.

Properties

Name	Type	Description
`calendar`	`Calendar`	The calendar system associated with this date, e.g. Gregorian.
`era`	`string`	The calendar era for this date, e.g. "BC" or "AD".
`year`	`number`	The year of this date within the era.
`month`	`number`	The month number within the year. Note that some calendar systems such as Hebrew may have a variable number of months per year. Therefore, month numbers may not always correspond to the same month names in different years.
`day`	`number`	The day number within the month.
`hour`	`number`	The hour in the day, numbered from 0 to 23.
`minute`	`number`	The minute in the hour.
`second`	`number`	The second in the minute.
`millisecond`	`number`	The millisecond in the second.
`timeZone`	`string`	The IANA time zone identifier that this date and time is represented in.
`offset`	`number`	The UTC offset for this time, in milliseconds.

Methods

Method	Description
`constructor( (...args: any[] )): void`
`copy(): ZonedDateTime`	Returns a copy of this date.
`add( (duration: DateTimeDuration )): void`	Returns a new `ZonedDateTime` with the given duration added to it.
`subtract( (duration: DateTimeDuration )): void`	Returns a new `ZonedDateTime` with the given duration subtracted from it.
`set( (fields: DateFields & & TimeFields, , disambiguation?: Disambiguation )): void`	Returns a new `ZonedDateTime` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: DateField \| \| TimeField, amount: number, options?: CycleTimeOptions ): void`	Returns a new `ZonedDateTime` with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.
`toDate(): void`	Converts the date to a native JavaScript Date object.
`toString(): void`	Converts the date to an ISO 8601 formatted string, including the UTC offset and time zone identifier.
`toAbsoluteString(): void`	Converts the date to an ISO 8601 formatted string in UTC.
`compare( (b: CalendarDate \| CalendarDateTime \| ZonedDateTime )): void`	Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after.

Name	Type	Default	Description
`locale`	`string`	—	The locale to display and edit the value according to.
`createCalendar`	`( (name: string )) => Calendar`	—	A function that creates a Calendar object for a given calendar identifier. Such a function may be imported from the `@internationalized/date` package, or manually implemented to include support for only certain calendars.
`visibleDuration`	`DateDuration`	`{months: 1}`	The amount of days that will be displayed at once. This affects how pagination works.
`selectionAlignment`	`'start' \| 'center' \| 'end'`	—	Determines how to align the initial selection relative to the visible date range.
`minValue`	`DateValue \| null`	—	The minimum allowed date that a user may select.
`maxValue`	`DateValue \| null`	—	The maximum allowed date that a user may select.
`isDateUnavailable`	`( (date: DateValue )) => boolean`	—	Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
`isDisabled`	`boolean`	`false`	Whether the calendar is disabled.
`isReadOnly`	`boolean`	`false`	Whether the calendar value is immutable.
`autoFocus`	`boolean`	`false`	Whether to automatically focus the calendar when it mounts.
`focusedValue`	`DateValue`	—	Controls the currently focused date within the calendar.
`defaultFocusedValue`	`DateValue`	—	The date that is focused when the calendar first mounts (uncountrolled).
`onFocusChange`	`( (date: CalendarDate )) => void`	—	Handler that is called when the focused date changes.
`isInvalid`	`boolean`	—	Whether the current selection is invalid according to application logic.
`errorMessage`	`ReactNode`	—	An error message to display when the selected value is invalid.
`pageBehavior`	`PageBehavior`	`visible`	Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
`value`	`DateValue \| null \| null`	—	The current value (controlled).
`defaultValue`	`DateValue \| null \| null`	—	The default value (uncontrolled).
`onChange`	`( (value: MappedDateValue<DateValue \| \| null> )) => void`	—	Handler that is called when the value changes.

The Calendar interface represents a calendar system, including information about how days, months, years, and eras are organized, and methods to perform arithmetic on dates.

Properties

Name	Type	Description
`identifier`	`string`	A string identifier for the calendar, as defined by Unicode CLDR.

Methods

Method	Description
`fromJulianDay( (jd: number )): CalendarDate`	Creates a CalendarDate in this calendar from the given Julian day number.
`toJulianDay( (date: AnyCalendarDate )): number`	Converts a date in this calendar to a Julian day number.
`getDaysInMonth( (date: AnyCalendarDate )): number`	Returns the number of days in the month of the given date.
`getMonthsInYear( (date: AnyCalendarDate )): number`	Returns the number of months in the year of the given date.
`getYearsInEra( (date: AnyCalendarDate )): number`	Returns the number of years in the era of the given date.
`getEras(): string[]`	Returns a list of era identifiers for the calendar.
`getMinimumMonthInYear( (date: AnyCalendarDate )): number`	Returns the minimum month number of the given date's year. Normally, this is 1, but in some calendars such as the Japanese, eras may begin in the middle of a year.
`getMinimumDayInMonth( (date: AnyCalendarDate )): number`	Returns the minimum day number of the given date's month. Normally, this is 1, but in some calendars such as the Japanese, eras may begin in the middle of a month.

Name	Type	Description
`calendar`	`Calendar`
`era`	`string`
`year`	`number`
`month`	`number`
`day`	`number`

Method	Description
`copy(): this`

Represents an amount of time in calendar-specific units, for use when performing arithmetic.

Name	Type	Description
`years`	`number`	The number of years to add or subtract.
`months`	`number`	The number of months to add or subtract.
`weeks`	`number`	The number of weeks to add or subtract.
`days`	`number`	The number of days to add or subtract.

'valid' | 'invalid'

'single' | 'visible'

DateValue | null extends ZonedDateTime ? ZonedDateTime :
DateValue | null extends CalendarDateTime ? CalendarDateTime :
DateValue | null extends CalendarDate ? CalendarDate : never

Properties

Name	Type	Description
`value`	`CalendarDate \| null`	The currently selected date.
`isDisabled`	`boolean`	Whether the calendar is disabled.
`isReadOnly`	`boolean`	Whether the calendar is in a read only state.
`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.
`minValue`	`DateValue \| null`	The minimum allowed date that a user may select.
`maxValue`	`DateValue \| null`	The maximum allowed date that a user may select.

Methods

Method	Description
`setValue( (value: CalendarDate \| \| null )): 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.

Name	Type	Description
`start`	`T`	The start value of the range.
`end`	`T`	The end value of the range.