ARIA 1.1 Combobox with Grid Popup Example

NOTE: Please provide feedback on this example in issue 500.

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: The primary difference between the ARIA 1.0 pattern and the ARIA 1.1 pattern is the placement of the combobox role.
    aria-haspopup=grid div Indicates that the combobox can popup a grid to suggest values.
    aria-owns=IDREF div Identifies the element that serves as the grid popup.
    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
    aria-labelledby=IDREF input[type="text"] Provides a label for the textbox element of the combobox.
    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 uses aria-owns instead of aria-controls.
    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