| |
| sidebar_position: 2 |
| |
|
|
| # Accessible Date Pickers |
|
|
| DayPicker follows the [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/) for date pickers, including features like keyboard navigation, focus management, and labeling. |
|
|
| Depending on your design, you might need to add more accessibility features. For example, when using [Input Fields](../guides/input-fields.mdx), there may be some limitations based on your accessibility goals. Keep up with best practices by following the [ARIA Patterns](https://www.w3.org/WAI/ARIA/apg/patterns/). |
|
|
| :::tip Accessibility Tips |
|
|
| - Test your date picker regularly with a screen reader to ensure accessibility. |
| - Use an `aria-live` region to announce when a date is selected, such as using the `footer` prop. |
| - Customize ARIA labels with the [`labels`](../api/interfaces/PropsBase.md#labels) prop for better user feedback. |
| - Maintain sufficient color contrast between text and background. |
| - Offer instructions for first-time users or those unfamiliar with the date picker. |
|
|
| ::: |
|
|
| ## Accessibility Props |
|
|
| | Prop Name | Type | Description | |
| | |
| | `labels` | [`Labels`](../api/type-aliases/Labels.md) | Map of the ARIA labels used within DayPicker for better accessibility. | |
| | `footer` | `ReactNode` \| `string` | Add a footer to the calendar, which can act as a [live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) to announce updates. | |
| | `role` | `application` \| `dialog` | Set the ARIA role for the container. Use `application` for a more interactive widget or `dialog` for a modal-like date picker. | |
| | `aria-label` | `string` | The label to use for the container when a `role` is set, providing a descriptive text for screen readers. | |
| | `aria-labelledby` | `string` | Reference another element that describes the calendar, such as a heading or external label, allowing assistive tech to announce that element as the calendar title. | |
| | `autoFocus` | `boolean` | Autofocus the calendar when it opens, improving keyboard navigation. | |
|
|
| ### Autofocusing the Calendar {#autofocus} |
|
|
| DayPicker automatically manages focus when users interact with the calendar. To enhance accessibility, you can autofocus the calendar when it opens by using the `autoFocus` prop: |
|
|
| ```tsx |
| <DayPicker mode="single" autoFocus /> |
| ``` |
|
|
| ## Keyboard Navigation |
|
|
| DayPicker supports keyboard navigation to make it easier for users to navigate the calendar. The following keys are supported: |
|
|
| | Keys | Function | |
| | |
| | <kbd>Arrow Up</kbd> | Move focus to the previous week. | |
| | <kbd>Shift + Arrow Up</kbd> | Move focus to the previous year. | |
| | <kbd>Arrow Right</kbd> | Move focus to the next day. | |
| | <kbd>Shift + Arrow Right</kbd> | Move focus to the next month. | |
| | <kbd>Arrow Down</kbd> | Move focus to the next week. | |
| | <kbd>Shift + Arrow Down</kbd> | Move focus to the next year. | |
| | <kbd>Arrow Left</kbd> | Move focus to the previous day. | |
| | <kbd>Shift + Arrow Left</kbd> | Move focus to the previous month. | |
| | <kbd>Page Up</kbd> | Move focus to the previous month. | |
| | <kbd>Page Down</kbd> | Move focus to the next month. | |
| | <kbd>Shift + Page Up</kbd> | Move focus to the previous year. | |
| | <kbd>Shift + Page Down</kbd> | Move focus to the next year. | |
| | <kbd>Home</kbd> | Move focus to the start of the week. | |
| | <kbd>End</kbd> | Move focus to the end of the week. | |
| | <kbd>Enter/Space</kbd> | Select the focused day. | |
|
|
| ## Getting Help With Accessibility |
|
|
| Accessibility is an evolving field. If you find any accessibility issues with DayPicker, please [open an issue](https://github.com/gpbl/react-day-picker/issues/new/choose). Your feedback helps improve our library's accessibility. |
| |
| Check out the [current accessibility issues](https://github.com/gpbl/react-day-picker/issues?q=is%3Aopen+label%3Aaccessibility+sort%3Aupdated-desc). |
| |
