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
Calendar supports selecting dates in many calendar systems used around the world, including Gregorian, Hebrew, Indian, Islamic, Buddhist, and more. Dates are automatically displayed in the appropriate calendar system for the user's locale. The calendar system can be overridden using the Unicode calendar locale extension, passed to the Provider component.
Selected dates passed to onChange always use the same calendar system as the value or defaultValue prop. If no value or defaultValue is provided, then dates passed to onChange are always in the Gregorian calendar since this is the most commonly used. This means that even though the user selects dates in their local calendar system, applications are able to deal with dates from all users consistently.
The below example displays a Calendar in the Hindi language, using the Indian calendar. Dates emitted from onChange are in the Gregorian calendar.
An aria-label must be provided to the Calendar for accessibility. If it is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.
In order to internationalize a Calendar, a localized string should be passed to the aria-label prop. For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the Calendar is automatically flipped. Dates are automatically formatted using the current locale.
Calendar accepts an onChange prop which is triggered whenever a date is selected by the user. The example below uses onChange to update a separate element with a formatted version of the date in the user's locale. This is done by converting the date to a native JavaScript Date object to pass to the formatter.
By default, Calendar allows selecting any date. The minValue and maxValue props can also be used to prevent the user from selecting dates outside a certain range.
Calendar supports marking certain dates as unavailable. These dates cannot be selected by the user and are displayed with a crossed out appearance. 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.
By default, the selected date is focused when a Calendar first mounts. If no value or defaultValue prop is provided, then the current date is focused. However, Calendar supports controlling which date is focused using the focusedValue and onFocusChange props. This also determines which month is visible. The defaultFocusedValue prop allows setting the initial focused date when the Calendar first mounts, without controlling it.
This example focuses July 1, 2021 by default. The user may change the focused date, and the onFocusChange event updates the state. Clicking the button resets the focused date back to the initial value.
import{CalendarDate}from'@internationalized/date';functionExample(){letdefaultDate=newCalendarDate(2021,7,1);let[focusedDate,setFocusedDate]=React.useState(defaultDate);return(<Flexdirection="column"alignItems="start"gap="size-200"><ActionButtononPress={()=>setFocusedDate(defaultDate)}>
Reset focused date
</ActionButton><CalendarfocusedValue={focusedDate}onFocusChange={setFocusedDate}/></Flex>);}
import{CalendarDate}from'@internationalized/date';functionExample(){letdefaultDate=newCalendarDate(2021,7,1);let[focusedDate,setFocusedDate]=React.useState(defaultDate);return(<Flexdirection="column"alignItems="start"gap="size-200"><ActionButtononPress={()=>setFocusedDate(defaultDate)}>
Reset focused date
</ActionButton><CalendarfocusedValue={focusedDate}onFocusChange={setFocusedDate}/></Flex>);}
import{CalendarDate}from'@internationalized/date';functionExample(){letdefaultDate=newCalendarDate(2021,7,1);let[focusedDate,setFocusedDate]=React.useState(defaultDate);return(<Flexdirection="column"alignItems="start"gap="size-200"><ActionButtononPress={()=>setFocusedDate(defaultDate)}>
Reset focused
date
</ActionButton><CalendarfocusedValue={focusedDate}onFocusChange={setFocusedDate}/></Flex>);}
By default, when pressing the next or previous buttons, pagination will advance by the visibleMonths value. This behavior can be changed to page by single months instead, by setting pageBehavior to single.
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'.
The month number within the year. Note that some calendar systems such as Hebrew
may have a variable number of months per year. Therefore, month numbers may not
always correspond to the same month names in different years.
Returns a new CalendarDate with the given field adjusted by a specified amount.
When the resulting value reaches the limits of the field, it wraps around.
The month number within the year. Note that some calendar systems such as Hebrew
may have a variable number of months per year. Therefore, month numbers may not
always correspond to the same month names in different years.
Returns a new CalendarDateTime with the given field adjusted by a specified amount.
When the resulting value reaches the limits of the field, it wraps around.
toDate(
(timeZone: string,
, disambiguation?: Disambiguation
)): Date
Converts the date to a native JavaScript Date object in the given time zone.
The month number within the year. Note that some calendar systems such as Hebrew
may have a variable number of months per year. Therefore, month numbers may not
always correspond to the same month names in different years.
Returns a new ZonedDateTime with the given field adjusted by a specified amount.
When the resulting value reaches the limits of the field, it wraps around.
toDate(): void
Converts the date to a native JavaScript Date object.
toString(): void
Converts the date to an ISO 8601 formatted string, including the UTC offset and time zone identifier.
toAbsoluteString(): void
Converts the date to an ISO 8601 formatted string in UTC.