useCalendarState

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

installyarn add react-stately
version3.17.0
usageimport {useCalendarState} from 'react-stately'

API#


useCalendarState( (props: CalendarStateOptions )): CalendarState

Interface#


Properties

NameTypeDescription
valueCalendarDateThe currently selected date.
isDisabledbooleanWhether the calendar is disabled.
isReadOnlybooleanWhether the calendar is in a read only state.
visibleRangeRangeValue<CalendarDate>The date range that is currently visible in the calendar.
timeZonestringThe time zone of the dates currently being displayed.
validationStateValidationStateThe current validation state of the selected value.
focusedDateCalendarDateThe currently focused date.
isFocusedbooleanWhether focus is currently within the calendar.
minValueDateValueThe minimum allowed date that a user may select.
maxValueDateValueThe maximum allowed date that a user may select.

Methods

MethodDescription
setValue( (value: CalendarDate )): voidSets the currently selected date.
setFocusedDate( (value: CalendarDate )): voidSets the focused date.
focusNextDay(): voidMoves focus to the next calendar date.
focusPreviousDay(): voidMoves focus to the previous calendar date.
focusNextRow(): voidMoves focus to the next row of dates, e.g. the next week.
focusPreviousRow(): voidMoves focus to the previous row of dates, e.g. the previous work.
focusNextPage(): voidMoves focus to the next page of dates, e.g. the next month if one month is visible.
focusPreviousPage(): voidMoves focus to the previous page of dates, e.g. the previous month if one month is visible.
focusSectionStart(): voidMoves focus to the start of the current section of dates, e.g. the start of the current month.
focusSectionEnd(): voidMoves 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(): voidSelects the currently focused date.
selectDate( (date: CalendarDate )): voidSelects the given date.
setFocused( (value: boolean )): voidSets whether focus is currently within the calendar.
isInvalid( (date: CalendarDate )): booleanReturns whether the given date is invalid according to the minValue and maxValue props.
isSelected( (date: CalendarDate )): booleanReturns whether the given date is currently selected.
isCellFocused( (date: CalendarDate )): booleanReturns whether the given date is currently focused.
isCellDisabled( (date: CalendarDate )): booleanReturns whether the given date is disabled according to the minValue,maxValue, andisDisabled` props.
isCellUnavailable( (date: CalendarDate )): booleanReturns whether the given date is unavailable according to the isDateUnavailable prop.
isPreviousVisibleRangeInvalid(): booleanReturns whether the previous visible date range is allowed to be selected according to the minValue prop.
isNextVisibleRangeInvalid(): booleanReturns whether the next visible date range is allowed to be selected according to the maxValue prop.
getDatesInWeek( (weekIndex: number, , startDate?: CalendarDate )): Array<CalendarDatenull>

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.