Calendar
A calendar displays one or more date grids and allows users to select a single date.
Source code | Usage guidelines
Features
- Flexible – Display one or more months at once, or a custom time range for use cases like a week view. Minimum and maximum values, unavailable dates, and non-contiguous selections are supported as well.
- International – Support for 13 calendar systems used around the world, including Gregorian, Buddhist, Islamic, Persian, and more. Locale-specific formatting, number systems, and right-to-left support are available as well.
- Accessible – Calendar cells can be navigated and selected using the keyboard, and localized screen reader messages are included to announce when the selection and visible date range change.
- Customizable – As with all of React Aria, the DOM structure and styling of all elements can be fully customized.
Examples
Basic Calendar
A simple calendar with navigation buttons and date selection.
Calendar with Value
Calendar with controlled and uncontrolled values.
Multi-Month Calendar
Display multiple months at once.
Calendar with Validation
Calendar with minimum date validation.
Calendar with Unavailable Dates
Calendar with weekends and specific date ranges marked as unavailable.
Calendar with Error Message
Calendar with validation error message for weekend selection.
Controlled Focus
Calendar with controlled focused date.
Disabled Calendar
Calendar in disabled state.
Read-Only Calendar
Calendar in read-only state.
Week View Calendar
Custom week view using hooks.
Component List
Calendar Stable
The main calendar component that contains date grids and navigation.
CalendarGrid Stable
Renders an individual month within a calendar.
CalendarCell Stable
Renders an individual date within a calendar grid.
CalendarGridHeader Stable
Renders the header within a calendar grid, displaying weekday names.
CalendarHeaderCell Stable
Renders a column header within a calendar grid header.
CalendarGridBody Stable
Renders the body within a calendar grid containing date cells.
Button Stable
Navigation buttons for previous/next month navigation.
Heading Stable
Displays the current month and year.
Text Stable
Used for error messages and additional text content.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | DateValue | — | The current value (controlled). |
defaultValue | DateValue | — | The default value (uncontrolled). |
onChange | (value: DateValue) => void | — | Handler that is called when the value changes. |
focusedValue | DateValue | — | Controls which date is focused and determines which month is visible. |
onFocusChange | (date: DateValue) => void | — | Handler that is called when the focused date changes. |
minValue | DateValue | — | The minimum allowed date that a user may select. |
maxValue | DateValue | — | The maximum allowed date that a user may select. |
isDisabled | boolean | false | Whether the calendar is disabled. |
isReadOnly | boolean | false | Whether the calendar value is immutable. |
isInvalid | boolean | false | Whether the current selection is invalid according to application logic. |
isDateUnavailable | (date: DateValue) => boolean | — | Callback that is called for each date of the calendar to determine if it is unavailable. |
visibleDuration | DateDuration | {months: 1} | Controls the duration of the visible date range. |
pageBehavior | 'single' | 'visible' | 'visible' | Controls the behavior of paging. |
Feedback
Help us improve this component by providing feedback, asking questions on GitHub, or updating this file.