Calendar
A calendar displays one or more date grids and allows users to select a single date.
Usage
Value
A Calendar has no selection by default. An initial, uncontrolled value can be provided to the Calendar 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.
Calendar supports values with both date and time components, but only allows users to modify the date. By default, Calendar 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 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 Behaviour
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.
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
Calendar 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.
The isDateUnavailable prop accepts a callback that is called to evaluate whether each visible date is unavailable.
This example includes multiple unavailable date ranges, e.g. dates when no appointments are available.
In addition, all weekends are unavailable. The minValue prop is also used to prevent selecting dates before today.
Error message
Calendar tries to avoid allowing the user to select invalid dates in the first place.
However, if according to application logic a selected date 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 is a weekday and not a weekend according to the current locale.
Disabled
A calendar can be disabled.
Read-only
A 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 calendar is invalid.
The number of months to display at once.
The inline style for the element. A function may be provided to compute the style based on component state.
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.
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 CSS className for the element. A function may be provided to compute the class based on component state.