Date Picker Combobox Example

Read This First

The code in this example is not intended for production environments. Before using it for any purpose, read this to understand why.

This is an illustrative example of one way of using ARIA that conforms with the ARIA specification.

There may be support gaps in some browser and assistive technology combinations, especially for mobile/touch devices. Testing code based on this example with assistive technologies is essential before considering use in production systems.
The ARIA and Assistive Technologies Project is developing measurements of assistive technology support for APG examples.
Robust accessibility can be further optimized by choosing implementation patterns that maximize use of semantic HTML and heeding the warning that No ARIA is better than Bad ARIA.

About This Example

The below date picker demonstrates an implementation of the Combobox Pattern that opens a dialog. The date picker dialog is opened by activating the choose date button or by moving keyboard focus to the combobox and pressing Down Arrow or Alt + Down Arrow. The dialog contains an implementation of the grid pattern for displaying a calendar and enabling selection of a date. Additional buttons in the dialog are available for changing the month and year shown in the grid.

Similar examples include:

Date Picker Dialog example: Demonstrates a dialog containing a calendar grid for choosing a date.
Select-Only Combobox: A single-select combobox with no text input that is functionally similar to an HTML select element.
Editable Combobox with Both List and Inline Autocomplete: An editable combobox that demonstrates the autocomplete behavior known as "list with inline autocomplete".
Editable Combobox with List Autocomplete: An editable combobox that demonstrates the autocomplete behavior known as "list with manual selection".
Editable Combobox Without Autocomplete: An editable combobox that demonstrates the behavior associated with aria-autocomplete=none.
Editable Combobox with Grid Popup: An editable combobox that presents suggestions in a grid, enabling users to navigate descriptive information about each suggestion.

Example

Date

(date format: mm/dd/yyyy)

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 combobox via aria-describedby, making it available to assistive technologies as an accessible description.
While the down arrow icon is excluded from the Tab sequence as specified in the combobox design pattern, it is made accessible to assistive technologies as the Choose Date button. This enables assistive technology users who might not have a keyboard, e.g., someone using a touch-based screen reader, to open the date picker dialog.
In the dialog, shortcut keys are assigned to the additional buttons for changing the month and year displayed in the calendar.
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 grid.
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.
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.
Focus and hover styling of the controls support operating system high contrast settings via 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 provides a placeholder space for focus and hover styling.

Keyboard Support

Combobox

Key	Function
`Down Arrow`, `ALT + Down Arrow`	Open the date picker dialog. If the combobox contains a valid date, moves focus to that date in the calendar grid. Otherwise, moves focus to current date, i.e., today's date.

Date Picker Dialog

Key	Function
`ESC`	Closes the dialog and moves focus to the combobox.
`TAB`	Moves focus to next element in the dialog `Tab` sequence. Note that, as specified in the Grid Pattern, only one element 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 element 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: Calendar Buttons

Key	Function
`Space`, `Enter`	Change the month and/or year displayed in the calendar grid.

Date Picker Dialog: Date Grid

Key	Function
`Space`	Selects the date. Updates the value of the `combobox` with the selected date.
`Enter`	Selects the date. Updates the value of the `combobox` with the selected date. Closes the dialog and moves focus to the `combobox`.
`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.
`PageUp`	Changes the grid of dates to the previous month. Moves focus to the day of the month that has the same number. If that day does not exist, moves focus to the last day of the month.
`Shift`+ `PageUp`	Changes the grid of dates to the same month in the previous year. Moves focus to the day of the month that has the same number. If that day does not exist, moves focus to the last day of the month.
`PageDown`	Changes the grid of dates to the next month. Moves focus to the day of the month that has the same number. If that day does not exist, moves focus to the last day of the month.
`Shift`+ `PageDown`	Changes the grid of dates to the same month in the next year. Moves focus to the day of the month that has the same number. If that day does not exist, moves focus to the last day of the month.

Date Picker Dialog: OK and Cancel Buttons

Key	Function
`Space`, `Enter`	Activates the button: "Cancel": Closes the dialog, moves focus to combobox, does not update combobox value. "OK": Closes the dialog, moves focus to combobox, updates date in combobox.

Role, Property, State, and Tabindex Attributes

Combobox

Role	Attribute	Element	Usage
`combobox`		`input`	Identifies the `input` element as a combobox.
	`aria-haspopup="dialog"`	`input`	Indicates that the combobox opens a dialog.
	`aria-expanded="false"`	`input`	Indicates that the combobox is collapsed, i.e., the "Choose Date" dialog is not displayed.
	`aria-expanded="true"`	`input`	Indicates that the combobox is expanded, i.e., the "Choose Date" dialog is open.
	`aria-autocomplete="none"`	`input`	Indicates the combobox does not support autocomplete.
	`aria-controls="IDREF"`	`input`	Identifies the element controlled by the combobox.
	`aria-describedby="IDREF"`	`input`	Identifies the element that provides an accessible description for the combobox, enabling assistive technologies to associate the date format description with the input.

Choose Date Button

Role	Attribute	Element	Usage
	`tabindex="-1"`	`button`	Excludes the button (i.e., the down arrow icon) from the `Tab` sequence as specified by the combobox design pattern.
	`aria-label="string"`	`button`	Defines the accessible name as "Choose Date", which matches the title of the dialog opened by activating the button.

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="Choose Date"`	`div`	Defines the accessible name for the dialog.
	`aria-live="polite"`	`h2`	Indicates that screen readers should automatically announce the element containing the currently displayed month and year when they change. The `polite` value indicates that other announcements should not be interrupted.
	`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 announce it after announcing focus change events. The `polite` value indicates that other announcements should not be interrupted.

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`, which is the `h2` that shows the month and year of the dates displayed in the grid.
	`tabindex="0"`	`td`	Makes the gridcell 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. This approach to managing focus is described in the section on Managing Focus Within Components Using a Roving tabindex.
	`tabindex="-1"`	`td`	Makes the gridcell focusable and excludes it from the dialog `Tab` sequence. Changed dynamically to `0` by the JavaScript when the gridcell 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. This approach to managing focus is described in the section on Managing Focus Within Components Using a Roving tabindex.
	`aria-selected="true"`	`td`	Indicates the cell is selected. Set on the gridcell representing the current value of the combobox; no other gridcells 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 an abbr attribute containing the full spelling of the name of the day for that column.

Javascript and CSS Source Code

CSS: combobox-datepicker.css
Javascript: combobox-datepicker.js

Date Picker Combobox Example

Read This First

About This Example

Example

December 2020

Accessibility Features

Keyboard Support

Combobox

Date Picker Dialog

Date Picker Dialog: Calendar Buttons

Date Picker Dialog: Date Grid

Date Picker Dialog: OK and Cancel Buttons

Role, Property, State, and Tabindex Attributes

Combobox

Choose Date Button

Date Picker Dialog

Date Picker Dialog: Calendar Navigation Buttons

Date Picker Dialog: Date Grid

Javascript and CSS Source Code

HTML Source Code