Hugging Face's logo

AbdulElahGwaith
/
react-day-picker

Model card Files
xet
Community
react-day-picker / website /docs /upgrading.mdx
AbdulElahGwaith's picture
AbdulElahGwaith
Upload folder using huggingface_hub
cf86710 verified
raw
history blame contribute delete
15.6 kB
 ---
sidebar_position: 5
---
# Upgrading to v9
This release includes significant updates related to accessibility, styles, internationalization, and performance. See the [changelog](./changelog.mdx) for the full list of changes.
## Upgrading from v7
If you are upgrading from v7, this guide is still valid. First, read the [migration guide from v7 to v8](../versioned_docs/version-8.10.1/upgrading.mdx), then follow the steps below.
## Checklist
### 1. Upgrade to the Latest Version
```bash npm2yarn
npm install react-day-picker@latest
```
If you are not using `date-fns` directly in your code (e.g., when using a [different locale](./localization/changing-locale.mdx)), remove it from your dependencies:
```bash npm2yarn
npm remove date-fns
```
### 2. Update Your Custom Styles
The default design has changed slightly. You may need to adjust DayPicker to match your design. See the [styling docs](./docs/styling.mdx) for more information.
### 3. Add the `onSelect` Prop When Using `selected`
The `selected` prop is now controlled. Add an `onSelect` prop to handle the selected state and keep it in sync with your component.
```diff
+ const [selected, setSelected] = useState<Date | undefined>(undefined);
<DayPicker
mode="single"
selected={selected} // controlled prop
+ onSelect={setSelected} // update the selected date
/>
```
### 4. Update Class Names
Class names for UI elements have been updated for clarity and consistency. If you use custom styles via the `classNames` or `styles` prop, update them accordingly.
For example, `day_disabled` is now `disabled`:
```diff
<DayPicker
classNames={{
- day_disabled: 'day-disabled',
+ disabled: 'day-disabled', // applies `.day_disabled` to disabled days
}}
/>
```
Additionally, the `day` element is now `day_button`, and the `cell` element is now `day`:
```diff
<DayPicker
classNames={{
- cell: 'day-cell',
+ day: 'day-cell',
- day: 'day-button',
+ day_button: 'day-button',
}}
/>
```
See the full list of updated class names in the [`DeprecatedUI`](./api/type-aliases/DeprecatedUI.md) type.
<details>
<summary>**List of Updated Class Names**</summary>
| 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. |
</details>
### 5. Replace `fromDate` and `toDate`
Replace `fromDate` and `toDate` with the `hidden`, `startMonth`, and `endMonth` props.
#### Example: Replace `fromDate`
```diff
<DayPicker
- fromDate={new Date(2010, 11, 03)}
+ startMonth={new Date(2010, 11)}
+ hidden={[{ before: new Date(2010, 11, 03) }]}
/>
```
#### Example: Replace `toDate`
```diff
<DayPicker
- toDate={new Date(2010, 11, 03)}
+ endMonth={new Date(2010, 11)}
+ hidden={[{ after: new Date(2010, 11, 03) }]}
/>
```
### 6. Update Tests and Translations
DayPicker's ARIA labels have been updated for clarity. Update your tests and translations accordingly.
#### Updated ARIA Labels
| Label | Old Label | New Label |
| ------------------------------------------------------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------- |
| [`labelDayButton`](./api/functions/labelDayButton)<br/>_ex_ ~`labelDay`~ | `21st November (Monday)` | `Monday, November 21st, 2024`<br/>`Monday, November 21st, 2024, selected`<br/>`Today, November 21st, 2024` |
| [`labelPrevious`](./api/functions/labelPrevious) | `Go to previous month` | `Go to the Previous Month` |
| [`labelNext`](./api/functions/labelNext) | `Go to next month` | `Go to the Next Month` |
| [`labelWeekNumber`](./api/functions/labelWeekNumber.md) | `Week nr. ##` | `Week ##` |
Update test selectors as needed:
```diff
- 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 year and communicates the selected and today status. See [Translating DayPicker](./guides/translation.mdx) for more information.
### 7. Update Formatters to Return a String
Formatters now return a `string` instead of a `ReactNode`. Update your code accordingly.
```diff
<DayPicker
formatters={{
- formatCaption: (month) => <strong>{format(month, "LLLL y")}</strong> // ❌ returned an element
+ formatCaption: (month) => format(month, "LLLL y") // ✅ return a string
}}
/>;
```
If you need to return a `ReactElement`, use a [custom component](./guides/custom-components.mdx):
```tsx
<DayPicker
formatters={{
formatCaption: (month) => format(month, "LLLL y"), // ✅ return a string
}}
components={{
Caption: ({ children }) => <strong>{children}</strong>, // ✅ return a ReactElement
}}
/>
```
### 8. Update Custom Components
If you use the `components` prop, update your code as some components have changed. See the [custom components guide](./guides/custom-components.mdx) for details.
```diff
<DayPicker
components={{
- IconRight: MyRightIcon,
- IconLeft: MyLeftIcon,
+ Chevron: (props) => {
+ if (props.orientation === "left") {
+ return <ChevronLeftIcon {...props} />;
+ }
+ return <ChevronRightIcon {...props} />;
+ },
}}
/>
```
<details>
<summary>**List of Updated Components**</summary>
| Component | Changes |
| -------------- | --------------------------------------------------------------------------- |
| `Caption` | Renamed to [`MonthCaption`](./api/functions/MonthCaption.md). |
| `Day` | Now renders a [`DayButton`](./api/functions/DayButton.md). |
| `DayContent` | Removed. Use [`formatDay`](./api/functions/formatDay.md) to change content. |
| `Head` | Removed. |
| `HeadRow` | Renamed to [`Weekdays`](./api/functions/Weekdays.md). |
| `IconDropdown` | Removed. The icon is rendered by [`Chevron`](./api/functions/Chevron.md). |
| `IconLeft` | Removed. The icon is rendered by [`Chevron`](./api/functions/Chevron.md). |
| `IconRight` | Removed. The icon is rendered by [`Chevron`](./api/functions/Chevron.md). |
| `Row` | Renamed to [`Week`](./api/functions/Week.md). |
</details>
### Deprecations
Deprecated props and types will be removed in the next major version. 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
```diff
<DayPicker
- fromYear={2010}
+ startMonth={new Date(2010, 0)} // January 2010
- toYear={2021}
+ endMonth={new Date(2021, 11)} // December 2021
/>
```
#### Deprecated Types
If you use TypeScript, some types have been deprecated for clarity and shorter names.
```diff
- import type { DayPickerDefaultProps } from 'react-day-picker';
+ import type { PropsBase } from 'react-day-picker';
```
See the source of [types/deprecated.ts](https://github.com/gpbl/react-day-picker/blob/next/src/types/deprecated.ts) for more details.
<details>
<summary>**List of Deprecated Types**</summary>
| Deprecated Type | Deprecation Reason |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| ~`Caption`~ | Renamed to [`MonthCaption`](./api/functions/MonthCaption.md). |
| ~`HeadRow`~ | Removed. |
| ~`Row`~ | Renamed to [`Week`](./api/functions/Week.md). |
| ~`DayPickerSingleProps`~ | Renamed to [`PropsSingle`](./api/interfaces/PropsSingle.md). |
| ~`DayPickerMultipleProps`~ | Renamed to [`PropsMulti`](./api/interfaces/PropsMulti.md). |
| ~`DayPickerRangeProps`~ | Renamed to [`PropsRange`](./api/interfaces/PropsRange.md). |
| ~`DayPickerDefaultProps`~ | Renamed to [`PropsBase`](./api/interfaces/PropsBase.md). |
| ~`DaySelectionMode`~ | Renamed to [`Mode`](./api/type-aliases/Mode.md). |
| ~`Modifier`~ | Will be removed. Use `string` instead. |
| ~`InternaModifier`~ | Split into [`DayFlag`](./api/enumerations/DayFlag) and [`SelectionState`](./api/enumerations/SelectionState). |
| ~`SelectSingleEventHandler`~ | Will be removed. Use [`PropsSingle["onSelect]`](./api/interfaces/PropsSingle.md) instead. |
| ~`SelectMultipleEventHandler`~ | Will be removed. Use [`PropsMulti["onSelect]`](./api/interfaces/PropsMulti.md) instead. |
| ~`SelectRangeEventHandler`~ | Will be removed. Use [`PropsRange["onSelect]`](./api/interfaces/PropsRange.md) instead. |
| ~`DayPickerProviderProps`~ | Not used anymore. |
| ~`useNavigation`~ | Included in [`useDayPicker`](./api/functions/useDayPicker.md). |
| ~`useDayRender`~ | Removed. Customize day rendering with the `htmlAttributes` prop in a custom `Day` component. |
| ~`ContextProvidersProps`~ | 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`~ | Will be removed. Use `DayEventHandler<React.FocusEvent \| React.KeyboardEvent>` instead. |
| ~`DayKeyboardEventHandler`~ | Will be removed. Use `DayEventHandler<React.KeyboardEvent>` instead. |
| ~`DayMouseEventHandler`~ | Will be removed. Use `DayEventHandler<React.MouseEvent>` instead. |
| ~`DayPointerEventHandler`~ | Will be removed. Use `DayEventHandler<React.PointerEvent>` instead. |
| ~`DayTouchEventHandler`~ | Will be removed. Use `DayEventHandler<React.TouchEvent>` instead. |
</details>