DatePicker
What component has
- If the dropdown with the calendar grid opens, then the current date gets the focus.
- If a date is selected, the accessible name of the "Date field" input is updated to include the selected date.
Keyboard support
Key | Function |
---|---|
Tab | Moves focus to the next focusable element. If the last element in the dropdown is focused, moves focus to the first element. |
Shift + Tab | Moves focus to the previous focusable element. If the first element in the dropdown is focused, moves focus to the last element. |
Enter , Space | Opens the dropdown. When the dropdown is open and focus is on the calendar, applies the selected date and closes the dropdown. |
Esc | Closes the dropdown and returns focus to the trigger. |
Up Arrow , Down Arrow | Moves selection to the same day of the previous or next week, respectively. |
Left Arrow , Right Arrow | Moves selection to the previous or next day, respectively. |
Roles and attributes
The following list describes roles and attributes that component already has.
Trigger
Component / element | Role / Attribute | Usage |
---|---|---|
DatePicker.Trigger | aria-label="Date field" | Defines the accessible name. |
aria-controls="IDREF" | Indicates which element this trigger opens. | |
DatePicker.Trigger > input | role="combobox" | Identifies the element as a combobox—a text input combined with a list of options. |
aria-haspopup="dialog" and inherits aria-controls="IDREF" from its parent. | aria-haspopup indicates that the element triggers a dialog. | |
aria-expanded="false/true" | Indicates whether the dialog is open or not. | |
aria-describedby="IDREF" | Provides the input with an accessible description by linking to a hint that explains the required data format. |
Popper and its content
Component / element | Role / Attribute | Usage |
---|---|---|
DatePicker.Popper | role="dialog" | Identifies the element as a dialog, indicating that its content is grouped and separated from the rest of the page content. |
DatePicker.Prev | aria-label="Previous period" | Defines the accessible name for the button. |
DatePicker.Next | aria-label="Next period" | Defines the accessible name for the button. |
DatePicker.Title | aria-live="polite" | Indicates that assistive technologies should automatically announce the displayed month and year when they change. |
DateRangePicker.Period | role="listbox" | Identifies an element that creates a list from which a user may select one or more static items. |
Calendar and days units
Component / element | Role / Attribute | Usage |
---|---|---|
DatePicker.Calendar , MonthPeaker.Calendar , DatePicker.Calendar > div | role="grid" | Identifies the calendar as a grid widget. |
CalendarDays.Unit | role="gridcell" | Identifies a cell in the grid. It's intended to mimic the functionality of the HTML <td> element. |
aria-label is created from gridcell 's content and DatePicker.Title | Defines the accessible name for the cell. | |
aria-selected="true/false" | Indicates the cell or a number of cells is selected or not. | |
aria-disabled="false" | Applies to gridcell with disabled prop. Indicates that the element is perceivable but disabled, so it's not operable. | |
aria-colindex="INDEX_VALUE" | Applied when not all columns are present in the DOM. Defines an element's column index or position with respect to the total number of columns within the grid . | |
aria-rowindex="INDEX_VALUE" | Applied when not all rows are present in the DOM. Defines an element's position with respect to the total number of rows within the grid . | |
CalendarWeekDays | role="row" | Identifies a row of cells within a tabular structure. A row contains one or more grid cells or column headers, within a grid . |
CalendarWeekDays.Unit | role="columnheader" | Identifies an element as a column header cell, similar to the native <th> element with column scope. |
Resources
- W3 date picker example has detailed information about the accordion accessible behavior.
- Find live examples of accessible inputs with different types in DigitalA11y project.
Other recommendations
For more accessibility recommendations, refer to the common Accessibility guide.
Automated screen reader testing
Intergalactic v15.29.0, React v18.2.0, Playwright v1.25.1, Guidepup v0.13.1, MacOS Monterey 12.
Running screen reader against this file.
1. Screen reader goes into the active element.
2. Screen reader says "In web content Date field group".
3. Screen reader goes into the active element.
4. Screen reader says "06/29/2020 Insertion at end of text. Date MM/DD/YYYY edit text".
5. Screen reader presses the "Backspace" button.
6. Screen reader says "0".
7. Screen reader presses the "Backspace" button.
8. Screen reader says "2".
9. Screen reader presses the "Backspace" button.
10. Screen reader says "0".
11. Screen reader presses the "Backspace" button.
12. Screen reader says "06/29".
13. Screen reader presses the "Backspace" button.
14. Screen reader says "9".
15. Screen reader presses the "Backspace" button.
16. Screen reader says "06".
17. Screen reader presses the "Backspace" button.
18. Screen reader says "6".
19. Screen reader presses the "Backspace" button.
20. Screen reader says "0".
21. Screen reader types "05".
22. Screen reader types "29".
23. Screen reader says "2".
24. Screen reader goes out of active element.
25. Screen reader says "Date field group".
26. Screen reader goes into the active element.
27. Screen reader says "05/29 Insertion at end of text. Date MM/DD/YYYY edit text".
28. Screen reader types "2000".
29. Screen reader says "05/29/2000 Insertion at end of text. Date MM/DD/YYYY edit text".
30. Screen reader goes out of active element.
31. Screen reader says "Date field group".
32. Screen reader goes to the next element.
33. Screen reader goes into the active element.
34. Screen reader says "from date MM/DD/YYYY edit text".
35. Screen reader types "05".
36. Screen reader says "05".
37. Screen reader types "29".
38. Screen reader says "29".
39. Screen reader types "2000".
40. Screen reader says "05/29/2000 Insertion at end of text. from date MM/DD/YYYY edit text".
41. Screen reader types "05".
42. Screen reader says "to date MM/DD/YYYY edit text".
43. Screen reader types "29".
44. Screen reader says "29".
45. Screen reader types "2000".
46. Screen reader says "05/29/2000 Insertion at end of text. to date MM/DD/YYYY edit text".
47. Screen reader goes out of active element.
48. Screen reader says "Date field group".