The example below includes a date input field and a button that opens a date picker that implements the Dialog (Modal) Pattern.
The dialog contains a calendar that uses the grid pattern to present buttons that enable the user to choose a day from the calendar.
Choosing a date from the calendar closes the dialog and populates the date input field.
When the dialog is opened, if the input field is empty, or does not contain a valid date, then the current date is focused in the calendar.
Otherwise, the focus is placed on the day in the calendar that matches the value of the date input field.
Modal Dialog Example: An example demonstrating multiple layers of modal dialogs with both small and large amounts of content.
Date Picker Combobox: An editable date input combobox that opens a dialog containing a calendar grid and buttons for navigating by month and year.
Example
(date format: mm/dd/yyyy)
February 2020
Su
Mo
Tu
We
Th
Fr
Sa
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
Accessibility Features
The description of the date format is associated with the text input via aria-describedby, making it available to assistive technologies as an accessible description.
After a date is chosen, the accessible name of the "Choose Date" button is changed to "Change Date, DATE_STRING" where DATE_STRING is the selected date.
So, when the dialog closes and focus returns to the button, screen reader users hear confirmation of the selected date.
In the dialog, shortcut keys are assigned to the additional buttons for changing the month and year displayed in the calendar.
The calendar heading displaying the month and year is marked up as a live region so screen reader users get feedback from the buttons and keyboard commands that change the month and year.
Keyboard help is displayed at the bottom of the dialog.
A live region is used to announce it to screen reader users when focus moves into the calendar grid.
To facilitate compact visual design in the calendar, the day names in the column headers are abbreviated to two characters.
However, this makes it more difficult for screen reader users to understand the day names.
So, full day names are provided to assistive technologies in the HTML abbr attribute on the column headers, enabling screen readers to announce the full names when users navigate the grid.
High contrast support for focus and hover styling of the controls in the dialog box use the CSS border property:
When a button or date cell receives focus a border is added.
When hovering over a button or date cell with a pointing device a border is added.
By default buttons and date cells do not have a border, padding is used as a placeholder for the added border for focus and hover styling.
Keyboard Support
Choose Date Button
Key
Function
Space, Enter
Open the date picker dialog.
Move focus to selected date, i.e., the date displayed in the date input text field.
If no date has been selected, places focus on the current date.
Date Picker Dialog
Key
Function
ESC
Closes the dialog and returns focus to the "Choose Date" button.
Tab
Moves focus to next element in the dialog Tab sequence.
Note that, as specified in the Grid Pattern, only one button in the calendar grid is in the Tab sequence.
If focus is on the last button (i.e., "OK"), moves focus to the first button (i.e. "Previous Year").
Shift + Tab
Moves focus to previous element in the dialog Tab sequence.
Note that, as specified in the Grid Pattern, only one button in the calendar grid is in the Tab sequence.
If focus is on the first button (i.e., "Previous Year"), moves focus to the last button (i.e. "OK").
Date Picker Dialog: Month/Year Buttons
Key
Function
Space, Enter
Change the month and/or year displayed in the calendar grid.
Date Picker Dialog: Date Grid
Key
Function
Space, Enter
Select the date, close the dialog, and move focus to the "Choose Date" button.
Update the value of the "Date" input with the selected date.
Update the accessible name of the "Choose Date" button to include the selected date.
Up Arrow
Moves focus to the same day of the previous week.
Down Arrow
Moves focus to the same day of the next week.
Right Arrow
Moves focus to the next day.
Left Arrow
Moves focus to the previous day.
Home
Moves focus to the first day (e.g Sunday) of the current week.
End
Moves focus to the last day (e.g. Saturday) of the current week.
Page Up
Changes the grid of dates to the previous month.
Sets focus on the same day of the same week.
If that day does not exist, then moves focus to the same day of the previous or next week.
Shift + Page Up
Changes the grid of dates to the previous Year.
Sets focus on the same day of the same week.
If that day does not exist, then moves focus to the same day of the previous or next week.
Page Down
Changes the grid of dates to the next month.
Sets focus on the same day of the same week.
If that day does not exist, then moves focus to the same day of the previous or next week.
Shift + Page Down
Changes the grid of dates to the next Year.
Sets focus on the same day of the same week.
If that day does not exist, then moves focus to the same day of the previous or next week.
Date Picker Dialog: OK and Cancel Buttons
Key
Function
Space, Enter
Activates the button:
"Cancel": Closes the dialog, moves focus to "Choose Date" button, does not update date in date input.
"OK": Closes the dialog, moves focus to "Choose Date" button, updates date in date input, updates accessible name of the "Choose Date" button to include the selected date.
Role, Property, State, and Tabindex Attributes
Textbox
Role
Attribute
Element
Usage
aria-describedby="IDREF"
input
Identifies the element that provides an accessible description for the textbox, enabling assistive technologies to associate the date format description with the input.
Choose Date Button
Role
Attribute
Element
Usage
aria-label="String"
button
The initial value of accessible name is "Choose Date".
When users select a date, the accessible name is changed to "Change Date, DATE_STRING" where DATE_STRING is the selected date.
Date Picker Dialog
Role
Attribute
Element
Usage
dialog
div
Identifies the element as a dialog .
aria-modal="true"
div
Indicates the dialog is modal.
aria-label="string"
div
Defines the accessible name for the dialog.
aria-live="polite"
h2
When the month and/or year changes the content of the h2 element is updated.
Indicates the h2 should be automatically announced by screen readers.
aria-live="polite"
div
Indicates the element that displays information about keyboard commands for navigating the grid should be automatically announced by screen readers.
The script slightly delays display of the information, so screen readers are more likely to read it after information related to change of focus.
Date Picker Dialog: Calendar Navigation Buttons
Role
Attribute
Element
Usage
aria-label="String"
button
Defines the accessible name of the button (e.g. "Next Year").
Date Picker Dialog: Date Grid
Role
Attribute
Element
Usage
grid
table
Identifies the table element as a grid widget.
Since the grid role is applied to a table element, the row, columnheader, and gridcell roles do not need to be specified because they are implied by tr, th, and td tags.
aria-labelledby="IDREF"
table
Identifies the element that provides the accessible name for the grid.
tabindex="0"
td
Makes the cell focusable and includes it in the dialog Tab sequence.
Set dynamically by the JavaScript when the element is to be included in the dialog Tab sequence.
At any given time, only one gridcell within the grid is in the dialog Tab sequence.
Identifies the cell containing the currently selected date, i.e., the date value present in the date input.
Only set on the cell containing the currently selected date; no other cells have aria-selected specified.
Note: Since the names of the days of the week in the column headers are abbreviated to two characters, they may be difficult to understand when announced by a screen reader.
An alternative column header name can be provided to screen readers by applying the abbr attribute to the th elements.
So, each th element includes a abbr attribute containing the full spelling of the name of the day for that column.
