Calendar

All-in-one date picker and date range picker component for date and range selection.

Overview

The calendar component is a date selector that allows the user to select a single date or a range of dates. Under the hood it uses React Aria (opens in a new tab) hooks in order to build an accessible component, and @internationalized/date (opens in a new tab) for date handling

Principal variants

This component can be used with 2 styles:

• DatePicker (single date selection) with an on-screen calendar variant and an input + popover variant. In turn, it presents the possibility of displaying it as a single calendar or dual calendar.

• DateRangePicker (date range selection) with an on-screen calendar variant and an input + popover variant. At the same time, it has the possibility of displaying it as a simple calendar or dual calendar.

Dependencies

• @internationalized/date (opens in a new tab)
• react-aria (opens in a new tab)
• react-stately (opens in a new tab)
• Button
• Popover

DatePicker

Calendar style

The as prop with a value of calendar will render the calendar directly on the screen.

Date picker style

The as prop with a value of date-picker will render an accessible input to choose the date and a button to open a popover containing the calendar.

Footer

The footer complements the calendar by displaying the time selector (if applicable) and action and cancellation buttons.

• Use the boolean timeFiled prop to show the time input.
• Use the boolean cancelButton prop to show a cancel button.
• Use the onCancelButton function prop to execute a callback when the user clicks on the cancellation button
• Use the boolean actionButton prop to show a cancel button.
• Use the onActionButton function prop to execute a callback when the user clicks on the action button.

If the prop of granularity is set to "day", it means that we do not want to show the time, so if we set that we want to show the time inputs but leave the granularity set to day, the time input will not be displayed.

Values and Events

DatePicker has no default selection. An initial uncontrolled value can be provided using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop.

The onChange event is triggered when the user selects a date. It returns a DateValue object with the selected date.

To format the date you can use either the native DateTimeFormat API or the useDateFormatter hook.

Validation

By default, DatePicker allows selecting any date. The minValue and maxValue props can also be used to prevent the user from selecting dates outside a certain range.

This example only accepts dates after today.

Unavailable dates

DatePicker 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.

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.

Disabled

The isDisabled boolean prop makes the Calendar disabled. Cells cannot be focused or selected.

Read only

The isReadOnly boolean prop makes the Calendar's value immutable. Unlike isDisabled, the Calendar remains focusable.

Granularity

The granularity prop allows you to control the smallest unit displayed in the calendar input when the as prop is "date-picker".

Hide time zone

When a ZonedDateTime object is provided as the value to DatePicker, the time zone abbreviation is displayed by default. However, if this is displayed elsewhere or implicit based on the usecase, it can be hidden using the hideTimeZone option. This option is only available when the as prop is "date-picker".

Hour cycle

By default, DatePicker displays times in either 12 or 24 hour hour format depending on the user's locale. However, this can be overridden using the hourCycle prop if needed for a specific usecase

Form

DateRangePicker

Calendar style

The as prop with a value of calendar will render the calendar directly on the screen.

Date picker style

The as prop with a value of date-picker will render an accessible input to choose the date and a button to open a popover containing the calendar.

Single and dual mode

The mode prop allows you to decide whether to display a single or dual calendar.

Year view

The year view allows you to display and select whole months instead of specific dates.

IMPORTANT: Each calendar item has the 1st day of each month. Therefore, it is essential that if we want to set initial values we do it with the first day of the month. Otherwise, the selection will not work correctly.

Decade view

The decade view allows you to display and select complete years instead of specific dates.

IMPORTANT: Each element of the calendar has the 1st day of each year. Therefore, it is essential that if we want to establish initial values we do it with the first day of the year. Otherwise, the selection will not work correctly.

Quarter view

The quarter view allows you to display and select complete quarters instead of specific dates.

IMPORTANT: Each element of the calendar has established the 1st day of each quarter (Q1 = January / Q2 = April / Q3 = July / Q4 = October). Therefore, it is essential that if we want to establish initial values we do it with the first day of each quarter. Otherwise, the selection will not work correctly.

Presets

The presets allows you to display buttons that allow you to select different common calendar settings

Footer

The footer complements the calendar by displaying the time selector (if applicable) and action and cancellation buttons.

• Use the boolean timeFiled prop to show the time input.
• Use the boolean cancelButton prop to show a cancel button.
• Use the onCancelButton function prop to execute a callback when the user clicks on the cancellation button
• Use the boolean actionButton prop to show a cancel button.
• Use the onActionButton function prop to execute a callback when the user clicks on the action button.

If the prop of granularity is set to "day", it means that we do not want to show the time, so if we set that we want to show the time inputs but leave the granularity set to day, the time input will not be displayed.

Values and Events

DateRangePicker has no default selection. An initial uncontrolled value can be provided using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop.

The onChange event is triggered when the user selects a date. It returns a range of DateValue object with the selected date.

To format the date you can use either the native DateTimeFormat API or the useDateFormatter hook.

Validation

By default, DateRangePicker allows selecting any date. The minValue and maxValue props can also be used to prevent the user from selecting dates outside a certain range.

This example only accepts dates after today.

Unavailable dates

DateRangePicker 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.

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.

Disabled

The isDisabled boolean prop makes the Calendar disabled. Cells cannot be focused or selected.

Read only

The isReadOnly boolean prop makes the Calendar's value immutable. Unlike isDisabled, the Calendar remains focusable.

Granularity

The granularity prop allows you to control the smallest unit displayed in the calendar input when the as prop is "date-picker".

Hide time zone

When a ZonedDateTime object is provided as the value to DateRangePicker, the time zone abbreviation is displayed by default. However, if this is displayed elsewhere or implicit based on the usecase, it can be hidden using the hideTimeZone option. This option is only available when the as prop is "date-picker".

Hour cycle

By default, DateRangePicker displays times in either 12 or 24 hour hour format depending on the user's locale. However, this can be overridden using the hourCycle prop if needed for a specific usecase

Form

API Reference

For details of the other properties available in the component, check the useDatePicker (opens in a new tab) and useDateRangePicker (opens in a new tab) hooks documentation in the hook props section of the API.