RangeCalendar
A range calendar displays one or more date grids and allows users to select a contiguous range of dates.
Usage
Value
A RangeCalendar has no selection by default. An initial, uncontrolled value can be provided to the RangeCalendar using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop.
Date values are provided using objects in the @internationalized/date package. This library handles correct international date manipulation across calendars, time zones, and other localization concerns.
RangeCalendar supports values with both date and time components, but only allows users to modify the date. By default, RangeCalendar will emit CalendarDate objects in the onChange event, but if a CalendarDateTime or ZonedDateTime object is passed as the value or defaultValue, values of that type will be emitted, changing only the date and preserving the time components.
Controlled
A range calendar can handle value state in controlled mode.
Multi-month
Multiple CalendarGrid elements can be rendered to show multiple months at once.
The visibleMonths prop should be provided to the Calendar component to specify how many months are visible.
Page Behavior
The pageBehavior prop allows you to control how the calendar navigates between months.
By default, the calendar will navigate by visibleMonths, but by setting pageBehavior to single, pagination will be by one month.
Fixed weeks
The isFixedWeeks prop allows you to control whether the calendar displays fixed weeks.
By default, the calendar will display variable weeks, but by setting isFixedWeeks to true, all months will be displayed with 6 weeks.
This ensures that the height of the calendar does not change when navigating between months.
Validation
Min and Max
The minValue and maxValue props can be used to limit the range of dates that a user can select.
Unavailable Dates
RangeCalendar supports marking certain dates as unavailable. These dates remain focusable with the keyboard so that navigation is consistent, but cannot be selected by the user. In this example, they are displayed in red. The isDateUnavailable prop accepts a callback that is called to evaluate whether each visible date is unavailable.
Note that by default, users may not select non-contiguous ranges, i.e. ranges that contain unavailable dates within them. Once a start date is selected, enabled dates will be restricted to subsequent dates until an unavailable date is hit. See below for an example of how to allow non-contiguous ranges.
This example includes multiple unavailable date ranges, e.g. dates when a rental house is not available. The minValue prop is also used to prevent selecting dates before today.
Non-contiguous ranges
The allowsNonContiguousRanges prop enables a range to be selected even if there are unavailable dates in the middle. The value emitted in the onChange event will still be a single range with a start and end property, but unavailable dates will not be displayed as selected. It is up to applications to split the full selected range into multiple as needed for business logic.
This example prevents selecting weekends, but allows selecting ranges that span multiple weeks.
Error message
RangeCalendar tries to avoid allowing the user to select invalid dates in the first place. However, if according to application logic a selected date range is invalid, the isInvalid prop can be set.
This alerts assistive technology users that the selection is invalid, and can be used for styling purposes as well. In addition, the errorMessage slot may be used to help the user fix the issue.
This example validates that the selected date range is a maximum of 1 week in duration.
Disabled
A range calendar can be disabled.
Read-only
A range calendar can be read-only.
Custom First Day of the Week
By default, the first day of the week is automatically set based on the current locale.
This can be changed by setting the firstDayOfWeek prop to "sun", "mon", "tue", "wed", "thu", "fri", or "sat".
Props
The error message to display when the range calendar is invalid.
The number of months to display at once.
Whether the calendar should always display 6 weeks.
When combined with isDateUnavailable, determines whether non-contiguous ranges,
i.e. ranges containing unavailable dates, may be selected.
The minimum allowed date that a user may select.
The maximum allowed date that a user may select.
Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
Whether the calendar is disabled.
Whether the calendar value is immutable.
Whether to automatically focus the calendar when it mounts.
Controls the currently focused date within the calendar.
The date that is focused when the calendar first mounts (uncountrolled).
Whether the current selection is invalid according to application logic.
Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
The day that starts the week.
Determines the alignment of the visible months on initial render based on the current selection or current date if there is no selection.
The current value (controlled).
The default value (uncontrolled).
A function to create a new Calendar
object for a given calendar identifier. If not provided, the createCalendar function
from @internationalized/date will be used.
The inline style for the element.
The CSS className for the element.
The children of the component.