useRangeCalendarState

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

installyarn add react-stately
version3.32.2
usageimport {useRangeCalendarState} from 'react-stately'

API#


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

Interface#


Properties

NameTypeDescription
valueRangeValue<DateValue>nullThe currently selected date range.
anchorDateCalendarDatenullThe current anchor date that the user clicked on to begin range selection.
highlightedRangeRangeValue<CalendarDate>nullThe currently highlighted date range.
isDraggingbooleanWhether the user is currently dragging over the calendar.
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.
isValueInvalidbooleanWhether the calendar is invalid.
focusedDateCalendarDateThe currently focused date.
isFocusedbooleanWhether focus is currently within the calendar.
minValueDateValuenullThe minimum allowed date that a user may select.
maxValueDateValuenullThe maximum allowed date that a user may select.

Methods

MethodDescription
setValue( (value: RangeValue<DateValue>null )): voidSets the currently selected date range.
highlightDate( (date: CalendarDate )): voidHighlights the given date during selection, e.g. by hovering or dragging.
setAnchorDate( (date: CalendarDatenull )): voidSets the anchor date that the user clicked on to begin range selection.
setDragging( (isDragging: boolean )): voidSets whether the user is dragging over the calendar.
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 useRangeCalendar in react-aria for an example of useRangeCalendarState.