ARIA 1.1 Combobox with Grid Popup Example

The following example combobox implements the combobox design 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

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 design 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
  • Clears the textbox
  • If the grid is displayed, closes it.
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 Using aria-activedescendant to Manage Focus.

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 popup.
  • Sets focus on the textbox.
  • Clears 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 design pattern.

Combobox Container

Role Attribute Element Usage
combobox div
  • Identifies the element as a combobox.
  • Note:
    • Unlike this ARIA 1.1 combobox, an ARIA 1.0 pattern would have the combobox role on the textbox input instead of a parent container of the textbox.
    • The ARIA 1.1 pattern demonstrated on this page enables screen reader users to perceive both the input and the popup when using reading mode (see note below about aria-owns).
aria-haspopup=grid div Indicates that the combobox can popup a grid to suggest values.
aria-owns=IDREF div
  • Refers to the element that serves as the grid popup.
  • Tells browsers to arrange the screen reader reading order so the grid, when it is visible, immediately follows the other elements inside the combobox, regardless of where the grid element is in the DOM.
aria-expanded=false div Indicates that the popup element is not displayed.
aria-expanded=true div Indicates that the popup element is displayed.

Textbox

Role Attribute Element Usage
id="string" input[type="text"]
  • Referenced by for attribute of label element to provide an accessible label.
  • Recommended labeling method for HTML input elements so clicking label focuses input.
aria-autocomplete=list input[type="text"] Indicates that the autocomplete behavior of the text 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.
  • Note:
    • In the ARIA 1.0 combobox pattern, the textbox has aria-owns instead of aria-controls.
    • In this ARIA 1.1 pattern, aria-owns is instead on the parent container so the popup element is a sibling of the textbox instead of a child of the textbox, making it perceivable by screen reader users as an element adjacent to the textbox when using a reading cursor or touch interface.
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 Using aria-activedescendant to Manage Focus.

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 of the combobox.
row div Identifies the element containing all the cells for a row.
aria-selected=true div
  • Specified on a row in the grid when it 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