Skip to content

Editable Combobox with Grid Popup Example

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.

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:

Example

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

HTML Source Code

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

Back to Top