Upgrading to v9

This release includes important updates related to accessibility, styles, internationalization and performance. See the changelog for the full list of changes.

Upgrading from v7

If you are upgrading from v7, this guide is still valid for you. Read first the migration guide from v7 to v8 and then follow the steps below.

Checklist

1. Upgrade to the latest version

npm
Yarn
pnpm

npm install react-day-picker@latest

yarn add react-day-picker@latest

pnpm add react-day-picker@latest

Remove date-fns from your dependencies if you are not using it directly in your code, like when using a different locale.

npm
Yarn
pnpm

npm remove date-fns

yarn remove date-fns

pnpm remove date-fns

2. Update your custom styles

The default design is slightly changed, so you may need to adjust DayPicker again to match your design. See the styling docs for more information.

3. Update the class names

This version updates the name of the UI elements to be more clear and consistent, so the class names have changed.

If you are using custom styles via classNames or styles prop, you will need to update some of them.

For example, day_disabled is now disabled:

 <DayPicker
   classNames={{
-    day_disabled: 'day-disabled',
+    disabled: 'day-disabled', // applies `.day_disabled` to disabled days
   }}
 />

Please note that the day element is now day_button, and that the cell element is now day:

 <DayPicker
   classNames={{
-    cell: 'day-cell',
+    day: 'day-cell',
-    day: 'day-button',
+    day_button: 'day-button',
   }}
 />

See the following list of updated class names. The DeprecatedUI type lists all the deprecated class names.

List of updated ClassNames

Old Name	New Name
`button`	`button_previous`, `button_next`
`button_reset`	`button_previous`, `button_next`
`caption`	`month_caption`
`caption_between`	Removed
`caption_dropdowns`	`dropdowns`
`caption_end`	Removed
`caption_start`	Removed
`cell`	`day` – ⚠️ The previous `day` element is now `day_button`.
`day_disabled`	`disabled`
`day_hidden`	`hidden`
`day_outside`	`outside`
`day_range_end`	`range_end`
`day_range_middle`	`range_middle`
`day_range_start`	`range_start`
`day_selected`	`selected`
`day_today`	`today`
`dropdown_icon`	`chevron`
`dropdown_month`	`months_dropdown`
`dropdown_year`	`years_dropdown`
`head`	Removed
`head_cell`	`weekday`
`head_row`	`weekdays`
`multiple_months`	Removed. Use `data-multiple-months` data attribute.
`nav_button`	`button_previous`, `button_next`
`nav_button_next`	`button_next`
`nav_button_previous`	`button_previous`
`nav_icon`	`chevron`, `button_next`, `button_previous`
`row`	`week`
`table`	`month_grid`
`tbody`	`weeks`
`tfoot`	`footer`
`vhidden`	Removed
`weeknumber`	`week_number`
`with_weeknumber`	Removed. Use `data-week-numbers` data attribute.

4. Remove use of `fromDate`, `toDate`

In case you are using fromDate or toDate, replace them with the hidden and startMonth, endMonth prop.

Removed prop	Notes
~~`fromDate`~~	Replace it with `startMonth` and the `hidden` prop and the `before` Matcher.
~~`toDate`~~	Replace it with `endMonth` the `hidden` prop and the `after` Matcher.

Example

To replace fromDate:

 <DayPicker
-   fromDate={new Date(2010, 11, 03)}
+   startMonth={new Date(2010, 11)}
+   hidden={[{ before: new Date(2010, 11, 03) }]}
 />

To replace toDate:

 <DayPicker
-   toDate={new Date(2010, 11, 03)}
+   endMonth={new Date(2010, 11)}
+   hidden={[{ after: new Date(2010, 11, 03) }]}
 />

5. Update tests and translations

DayPicker relies on ARIA labels to make the calendar accessible, and v9 include some updates to make them more clear and descriptive. Following the upgrade, you may need to update your tests and translations.

Updated ARIA labels

The following ARIA labels have been updated:

Label	Old label	New label
`labelDayButton` ex ~~`labelDay`~~	`21st November (Monday)`	`Monday, November 21st, 2024` `Monday, November 21st, 2024, selected` `Today, November 21st, 2024`
`labelPrevious`	`Go to previous month`	`Go to the Previous Month`
`labelNext`	`Go to next month`	`Go to the Next Month`
`labelWeekNumber`	`Week nr. ##`	`Week ##`

You may need to update your test selectors — for example:

./test.js
- screen.getByRole('button', 'Go to next month');
+ screen.getByRole('button', 'Go to the Next Month');

`labelDay` changes

The labelDay function has been renamed to labelDayButton. It now includes the the year and communicates the selected and today status. See Translating DayPicker for more information.

6. Update formatters to return a string

The formatters now are functions returning a string instead of a ReactNode. In case you are using the formatters, update your code to return a string.

  <DayPicker
    formatters={{
-      formatCaption: (month) => <strong>{format(month, "LLLL y")}</strong> // ❌ returned an element
+      formatCaption: (month) => format(month, "LLLL y") // ✅ return a string
    }}
  />;

If your formatters are returning a ReactNode, you can use a custom component to return a ReactElement:

<DayPicker
  formatters={{
    formatCaption: (month) => format(month, "LLLL y") // ✅ return a string
  }}
  components={{
    Caption: ({ children }) => <strong>{children}</strong> // ✅ return a ReactElement
  }}
/>

7. Update your Custom Components

In case you are using the components prop, you may need to update your code, as some components have been updated.

DayPicker now allows to change any of its components. See the custom component guide and the updated CustomComponents type.

  <DayPicker
    components={{
-     IconRight: MyRightIcon,
-     IconLeft: MyLeftIcon,
+     Chevron: (props) => {
+       if (props.orientation === "left") {
+         return <ChevronLeftIcon {...props} />;
+       }
+       return <ChevronRightIcon {...props} />;
+     },
    }}
  />

List of Updated Components

Components	Changes
`Caption`	Renamed to `MonthCaption`.
`Day`	Now it renders a `DayButton`.
`DayContent`	Removed. Change its content with `formatDay`.
`Head`	Removed.
`HeadRow`	Renamed to `Weekdays`.
`IconDropdown`	Removed. The icon is rendered by `Chevron`.
`IconLeft`	Removed. The icon is rendered by `Chevron`.
`IconRight`	Removed. The icon is rendered by `Chevron`.
`Row`	Renamed to `Week`.

DayPicker hooks

In v8, you could use the DayPicker Hooks to access the DayPicker state and methods. In v9, these have been merged in the updated useDayPicker hook.

Deprecations

Deprecated props and types will be removed in the next major version, and it is recommended to update your code to avoid breaking changes.

Deprecated props

Deprecated prop	Replacement	Notes
~~`fromMonth`~~	`startMonth`	Renamed. The start month for the navigation.
~~`toMonth`~~	`endMonth`	Renamed. The end month for the navigation.
~~`fromYear`~~	`startMonth`	Pass the first month of the year to `startMonth`
~~`toYear`~~	`endMonth`	Pass the last month of the year to `endMonth`.

Example

  <DayPicker
-   fromYear={2010}
+   startMonth={new Date(2010, 0)}  // January 2010
-   toYear={2021}
+   endMonth={new Date(2021, 11)} // December 2021
  />

Deprecated types

If you are using TypeScript, some typings have been deprecated in favor of clarity and shorter names.

- import type { DayPickerDefaultProps } from 'react-day-picker';
+ import type { PropsBase } from 'react-day-picker';

See also the source of types/deprecated.ts.

List of Deprecated Types

Deprecated Type	Deprecation Reason
~~`Caption`~~	This component has been renamed. Use `MonthCaption` instead.
~~`HeadRow`~~	This component has been removed.
~~`Row`~~	This component has been renamed. Use `Week` instead.
~~`DayPickerSingleProps`~~	This type has been renamed. Use `PropsSingle` instead.
~~`DayPickerMultipleProps`~~	This type has been renamed. Use `PropsMulti` instead.
~~`DayPickerRangeProps`~~	This type has been renamed. Use `PropsRange` instead.
~~`DayPickerDefaultProps`~~	This type has been renamed. Use `PropsBase` instead.
~~`DaySelectionMode`~~	This type has been renamed. Use `Mode` instead.
~~`Modifier`~~	This type will be removed. Use `string` instead.
~~`InternaModifier`~~	This type has been split into `DayFlag` and `SelectionState`
~~`SelectSingleEventHandler`~~	This type will be removed. Use `PropsSingle["onSelect]` instead.
~~`SelectMultipleEventHandler`~~	This type will be removed. Use `PropsMulti["onSelect]` instead.
~~`SelectRangeEventHandler`~~	This type will be removed. Use `PropsRange["onSelect]` instead.
~~`DayPickerProviderProps`~~	This type is not used anymore.
~~`useNavigation`~~	This type has been included in `useDayPicker`.
~~`useDayRender`~~	This hook has been removed. To customize the rendering of a day, use the `htmlAttributes` prop in a custom `Day` component.
~~`ContextProvidersProps`~~	This type is not used anymore.
~~`DayLabel`~~	Use `typeof labelDay` instead.
~~`NavButtonLabel`~~	Use `typeof labelNext` or `typeof labelPrevious` instead.
~~`WeekdayLabel`~~	Use `typeof labelWeekday` instead.
~~`WeekNumberLabel`~~	Use `typeof labelWeekNumber` instead.
~~`DayClickEventHandler`~~	Use `DayMouseEventHandler` instead.
~~`DayFocusEventHandler`~~	This type will be removed. Use `DayEventHandler<React.FocusEvent \| React.KeyboardEvent>` instead.
~~`DayKeyboardEventHandler`~~	This type will be removed. Use `DayEventHandler<React.KeyboardEvent>` instead.
~~`DayMouseEventHandler`~~	This type will be removed. Use `DayEventHandler<React.MouseEvent>` instead.
~~`DayPointerEventHandler`~~	This type will be removed. Use `DayEventHandler<React.PointerEvent>` instead.
~~`DayTouchEventHandler`~~	This type will be removed. Use `DayEventHandler<React.TouchEvent>` instead.

Upgrading from v7​

Checklist​

1. Upgrade to the latest version​

2. Update your custom styles​

3. Update the class names​

4. Remove use of fromDate, toDate​

Example​

5. Update tests and translations​

Updated ARIA labels​

labelDay changes​

6. Update formatters to return a string​

7. Update your Custom Components​

DayPicker hooks​

Deprecations​

Deprecated props​

Example​

Deprecated types​

Upgrading from v7

Checklist

1. Upgrade to the latest version

2. Update your custom styles

3. Update the class names

4. Remove use of `fromDate`, `toDate`

Example

5. Update tests and translations

Updated ARIA labels

`labelDay` changes

6. Update formatters to return a string

7. Update your Custom Components

DayPicker hooks

Deprecations

Deprecated props

Example

Deprecated types