Design System
Forms

Calendar

The raw month grid behind Date picker and Date range picker. Reach for it directly only when you need the grid without a field.

Storybook (opens in a new tab)

Not documented yet

This component ships in the design system and is fully supported. What is missing is the guidance around it: when to reach for it, the do and don't, and the accessibility notes. Until that is written, Storybook is the reference for variants, props and live controls.

Props

PropTypeDefaultDescription
mode"single" | "multiple" | "range" | undefined—Enable the selection of a single day, multiple days, or a range of days.
requiredboolean | undefined—Whether the selection is required.
classNamestring | undefined—Class name to add to the root element.
classNames(Partial<ClassNames> & Partial<DeprecatedUI<string>>) | undefined—Change the class names used by DayPicker. Use this prop when you need to change the default class names — for example, when importing the style via CSS modules or when using a CSS framework.
modifiersClassNamesModifiersClassNames | undefined—Change the class name for the day matching the `modifiers`.
styleReact.CSSProperties | undefined—Style to apply to the root element.
styles(Partial<Styles> & Partial<DeprecatedUI<React.CSSProperties>>) | undefined—Change the inline styles of the HTML elements.
modifiersStylesModifiersStyles | undefined—Change the class name for the day matching the {@link modifiers}.
idstring | undefined—A unique id to add to the root element.
defaultMonthDate | undefinedThe current monthThe initial month to show in the calendar. Use this prop to let DayPicker control the current month. If you need to set the month programmatically, use {@link month} and {@link onMonthChange}.
monthDate | undefined—The month displayed in the calendar. As opposed to `defaultMonth`, use this prop with `onMonthChange` to change the month programmatically.
numberOfMonthsnumber | undefined1The number of displayed months.
startMonthDate | undefined—The earliest month to start the month navigation.
fromDatedeprecatedDate | undefined——
fromMonthdeprecatedDate | undefined——
fromYeardeprecatednumber | undefined——
endMonthDate | undefined—The latest month to end the month navigation.
toDatedeprecatedDate | undefined——
toMonthdeprecatedDate | undefined——
toYeardeprecatednumber | undefined——
pagedNavigationboolean | undefined—Paginate the month navigation displaying the `numberOfMonths` at a time.
reverseMonthsboolean | undefined—Render the months in reversed order (when {@link numberOfMonths} is set) to display the most recent month first.
hideNavigationboolean | undefined—Hide the navigation buttons. This prop won't disable the navigation: to disable the navigation, use {@link disableNavigation}.
disableNavigationboolean | undefined—Disable the navigation between months. This prop won't hide the navigation: to hide the navigation, use {@link hideNavigation}.
captionLayout"label" | "dropdown" | "dropdown-months" | "dropdown-years" | undefined—Show dropdowns to navigate between months or years. - `label`: Displays the month and year as a label. Default value. - `dropdown`: Displays dropdowns for both month and year navigation. - `dropdown-months`: Displays a dropdown only for the month navigation. - `dropdown-years`: Displays a dropdown only for the year navigation. **Note:** By default, showing the dropdown will set the {@link startMonth} to 100 years ago and {@link endMonth} to the end of the current year. You can override this behavior by explicitly setting `startMonth` and `endMonth`.
reverseYearsboolean | undefined—Reverse the order of years in the dropdown when using `captionLayout="dropdown"` or `captionLayout="dropdown-years"`.
navLayout"around" | "after" | undefined—Adjust the positioning of the navigation buttons. - `around`: Displays the buttons on either side of the caption. - `after`: Displays the buttons after the caption. This ensures the tab order matches the visual order. If not set, the buttons default to being displayed after the caption, but the tab order may not align with the visual order.
fixedWeeksboolean | undefined—Display always 6 weeks per each month, regardless of the month’s number of weeks. Weeks will be filled with the days from the next month.
hideWeekdaysboolean | undefined—Hide the row displaying the weekday row header.
showOutsideDaysboolean | undefined—Show the outside days (days falling in the next or the previous month). **Note:** when a {@link broadcastCalendar} is set, this prop defaults to true.
showWeekNumberboolean | undefined—Show the week numbers column. Weeks are numbered according to the local week index.
animateboolean | undefined—Animate navigating between months.
broadcastCalendarboolean | undefined—Display the weeks in the month following the broadcast calendar. Setting this prop will ignore {@link weekStartsOn} (always Monday) and {@link showOutsideDays} will default to true.
ISOWeekboolean | undefined—Use ISO week dates instead of the locale setting. Setting this prop will ignore `weekStartsOn` and `firstWeekContainsDate`.
timeZonestring | undefined—The time zone (IANA or UTC offset) to use in the calendar (experimental). See [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for the possible values.
noonSafeboolean | undefined—Keep calendar math at noon in the configured {@link timeZone} to avoid historical second-level offsets drifting dates across midnight. This prop sets the time of the dates to noon (12:00).
componentsPartial<CustomComponents> | undefined—Change the components used for rendering the calendar elements.
footerReact.ReactNode—Add a footer to the calendar, acting as a live region. Use this prop to communicate the calendar's status to screen readers. Prefer strings over complex UI elements.
autoFocusboolean | undefined—When a selection mode is set, DayPicker will focus the first selected day (if set) or today's date (if not disabled). Use this prop when you need to focus DayPicker after a user action, for improved accessibility.
initialFocusdeprecatedboolean | undefined——
disabledMatcher | Matcher[] | undefined—Apply the `disabled` modifier to the matching days. Disabled days cannot be selected when in a selection mode is set.
hiddenMatcher | Matcher[] | undefined—Apply the `hidden` modifier to the matching days. Will hide them from the calendar.
todayDate | undefined—The today’s date. Default is the current date. This date will get the `today` modifier to style the day.
modifiersRecord<string, Matcher | Matcher[] | undefined> | undefined—Add modifiers to the matching days.
labelsPartial<Labels> | undefined—Labels creators to override the defaults. Use this prop to customize the aria-label attributes in DayPicker.
formattersPartial<Formatters> | undefined—Formatters used to format dates to strings. Use this prop to override the default functions.
dirstring | undefined—The text direction of the calendar. Use `ltr` for left-to-right (default) or `rtl` for right-to-left.
aria-labelstring | undefined—The aria-label attribute to add to the container element.
aria-labelledbystring | undefined—The aria-labelledby attribute to add to the container element.
role"application" | "dialog" | undefined—The role attribute to add to the container element.
noncestring | undefined—A cryptographic nonce ("number used once") which can be used by Content Security Policy for the inline `style` attributes.
titlestring | undefined—Add a `title` attribute to the container element.
langstring | undefined—Add the language tag to the container element. When omitted, DayPicker uses the active locale code (`locale.code`). Set this prop to override the language tag.
localePartial<DayPickerLocale> | undefinedenUS - The English locale default of `date-fns`.The locale object used to localize dates. Pass a locale from `react-day-picker/locale` to localize the calendar.
numeralsNumerals | undefined`latn` Latin (Western Arabic)The numeral system to use when formatting dates. - `latn`: Latin (Western Arabic) - `arab`: Arabic-Indic - `arabext`: Eastern Arabic-Indic (Persian) - `deva`: Devanagari - `beng`: Bengali - `guru`: Gurmukhi - `gujr`: Gujarati - `orya`: Oriya - `tamldec`: Tamil - `telu`: Telugu - `knda`: Kannada - `mlym`: Malayalam
weekStartsOn0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined—The index of the first day of the week (0 - Sunday). Overrides the locale's default.
firstWeekContainsDate1 | 4 | undefined—The day of January that is always in the first week of the year.
useAdditionalWeekYearTokensboolean | undefined—Enable `DD` and `DDDD` for week year tokens when formatting or parsing dates.
useAdditionalDayOfYearTokensboolean | undefined—Enable `YY` and `YYYY` for day of year tokens when formatting or parsing dates.
onMonthChangeMonthChangeEventHandler | undefined—Event fired when the user navigates between months.
onNextClickMonthChangeEventHandler | undefined—Event handler when the next month button is clicked.
onPrevClickMonthChangeEventHandler | undefined—Event handler when the previous month button is clicked.
onWeekNumberClickdeprecatedany—Event handler when a week number is clicked.
onDayClickDayEventHandler<React.MouseEvent<Element, MouseEvent>> | undefined—Event handler when a day is clicked.
onDayFocusDayEventHandler<React.FocusEvent<Element, Element>> | undefined—Event handler when a day is focused.
onDayBlurDayEventHandler<React.FocusEvent<Element, Element>> | undefined—Event handler when a day is blurred.
onDayKeyDownDayEventHandler<React.KeyboardEvent<Element>> | undefined—Event handler when a key is pressed on a day.
onDayMouseEnterDayEventHandler<React.MouseEvent<Element, MouseEvent>> | undefined—Event handler when the mouse enters a day.
onDayMouseLeaveDayEventHandler<React.MouseEvent<Element, MouseEvent>> | undefined—Event handler when the mouse leaves a day.
dateLibPartial<DateLib> | undefined—Replace the default date library with a custom one. Experimental: not guaranteed to be stable (may not respect semver).
onDayKeyUpdeprecatedDayEventHandler<React.KeyboardEvent<Element>> | undefined——
onDayKeyPressdeprecatedDayEventHandler<React.KeyboardEvent<Element>> | undefined——
onDayPointerEnterdeprecatedDayEventHandler<React.PointerEvent<Element>> | undefined——
onDayPointerLeavedeprecatedDayEventHandler<React.PointerEvent<Element>> | undefined——
onDayTouchCanceldeprecatedDayEventHandler<React.TouchEvent<Element>> | undefined——
onDayTouchEnddeprecatedDayEventHandler<React.TouchEvent<Element>> | undefined——
onDayTouchMovedeprecatedDayEventHandler<React.TouchEvent<Element>> | undefined——
onDayTouchStartdeprecatedDayEventHandler<React.TouchEvent<Element>> | undefined——

Date range pickerPlanned

Pick a start and end date together, with presets for the ranges people ask for most.

File uploadPlanned

A drop target and file list for attaching documents such as receipts, referral letters and claim evidence.

On this page

Props