Editable Combobox with Grid Popup 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 following example combobox implements the combobox pattern using a grid for the suggested values popup.

In this example, users can specify the name of a fruit or vegetable by either typing a value in the box or choosing from the set of values presented in a grid popup. The popup becomes available after the textbox contains a character that matches the beginning of the name of one of the items in the set of value suggestions. Users may type any value in the textbox; this implementation does not limit input to values that are in the set of value suggestions.

The grid that presents suggested values has two columns. Each row of the grid represents one suggestion; column one contains the name of the fruit or vegetable and column two identifies whether it is a fruit or vegetable.

Similar examples include:

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.
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

Fruits and vegetables

Accessibility Features

Browsers do not manage visibility of elements referenced by aria-activedescendant like they do for elements with focus. When a keyboard event changes the active option in the listbox, the JavaScript scrolls the option referenced by aria-activedescendant into view. Managing aria-activedescendant visibility is essential to accessibility for people who use a browser's zoom feature to increase the size of content.

Keyboard Support

The example combobox on this page implements the following keyboard interface. Other variations and options for the keyboard interface are described in the Keyboard Interaction section of the combobox pattern.

Textbox

Key	Function
`Down Arrow`	If the grid is displayed, moves focus to the first suggested value.
`Up Arrow`	If the grid is displayed, moves focus to the last suggested value.
`Escape`	If the grid is displayed, closes it. If the grid is not displayed, clears the textbox.
Standard single line text editing keys	Keys used for cursor movement and text manipulation, such as `Delete` and `Shift + Right Arrow`. An HTML `input` with `type=text` is used for the textbox so the browser will provide platform-specific editing keys.

Grid Popup

NOTE: When visual focus is in the grid, DOM focus remains on the textbox and the value of aria-activedescendant on the textbox is set to a value that refers to an element in the grid that is visually indicated as focused. Where the following descriptions of keyboard commands mention focus, they are referring to the visual focus indicator. For more information about this focus management technique, see Managing Focus in Composites Using aria-activedescendant.

Key	Function
`Enter`	Sets the textbox value to the content of the first cell in the row containing focus. Closes the grid popup. Sets focus on the textbox.
`Escape`	Closes the grid. Sets visual focus on the textbox.
`Down Arrow`	Moves focus to the next row. If focus is in the last row, moves focus to the first row. Note: This wrapping behavior is useful when `Home` and `End` move the editing cursor as described below.
`Up Arrow`	Moves focus to the previous row. If focus is in the first row, moves focus to the last row. Note: This wrapping behavior is useful when `Home` and `End` move the editing cursor as described below.
`Right Arrow`	Moves focus to the next cell. If focus is in the last cell in a row, moves focus to the first cell in the next row. If focus is in the last cell in the last row, moves focus to the first cell in the first row.
`Left Arrow`	Moves focus to the previous cell. If focus is in the first cell in a row, moves focus to the last cell in the previous row. If focus is in the first cell in the first row, moves focus to the last cell in the last row.
`Home`	Moves focus to the textbox and places the editing cursor at the beginning of the field.
`End`	Moves focus to the textbox and places the editing cursor at the end of the field.
Printable Characters	Moves focus to the textbox. Types the character in the textbox.

Role, Property, State, and Tabindex Attributes

The example comboboxes on this page implement the following ARIA roles, states, and properties. Information about other ways of applying ARIA roles, states, and properties is available in the Roles, States, and Properties section of the combobox pattern.

Textbox

Role	Attribute	Element	Usage
`combobox`		`input[type="text"]`	Identifies the element as a combobox.
	`aria-haspopup="grid"`	`input[type="text"]`	Indicates that the combobox can popup a `grid` to suggest values.
	`aria-expanded="false"`	`input[type="text"]`	Indicates that the popup element is not displayed.
	`aria-expanded="true"`	`input[type="text"]`	Indicates that the popup element is displayed.
	`id="string"`	`input[type="text"]`	Referenced by `for` attribute of `label` element to provide an accessible name. Recommended naming method for HTML input elements because clicking label focuses input.
	`aria-autocomplete="list"`	`input[type="text"]`	Indicates that the autocomplete behavior of the input is to suggest a list of possible values in a popup.
	`aria-controls="IDREF"`	`input[type="text"]`	Identifies the popup element that lists suggested values.
	`aria-activedescendant="IDREF"`	`input[type="text"]`	When a cell in the grid is visually indicated as having keyboard focus, refers to that cell. When navigation keys, such as `Down Arrow`, are pressed, the JavaScript changes the value. Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the `input` element. For more information about this focus management technique, see Managing Focus in Composites Using aria-activedescendant.

Grid Popup

Role	Attribute	Element	Usage
`grid`		`div`	Identifies the element as a `grid`.
	`aria-labelledby="IDREF"`	`div`	Provides a label for the `grid` element controlled by the combobox.
`row`		`div`	Identifies the element containing all the cells for a row.
	`aria-selected="true"`	`div`	Specified on a cell when the row containing the cell is visually indicated as selected. Occurs only when a cell in the grid is referenced by `aria-activedescendant`.
`gridcell`		`div`	Identifies the element containing the content for a single cell.

JavaScript and CSS Source Code

CSS: grid-combo.css
Javascript: grid-combo.js, grid-combo-example.js, utils.js

HTML Source Code

To copy the following HTML code, please open it in CodePen.