Accessibility Examples: ARIA Combo Box

The ARIA combo box widget is a composite widget, consisting of a single-line textbox and a popup element containing suggested values for the textbox. The popup is typically hidden by default, and it may be one of four widget types:

It is common for a combo box widget to also have a button adjacent to the textbox for expanding or collapsing the popup.

ARIA 1.1 Implementation

Example 1 illustrates an ARIA 1.1 implementation of a combo box with the same features. The ARIA 1.1 implementation pattern is not yet well supported by assistive technologies.

The combo box has list autocomplete and automatic selection behavior. This means that as the user types, the popup list will expand and display options that correspond to what the user has typed in the textbox. The first option in the list is automatically selected and will become the value of the textbox, unless the user selects another option from the list or changes what has been typed in the textbox.

See the Combo Box section of the WAI-ARIA Authoring Practices 1.1 document for more information about the ARIA combo box widget.

Example 1: ARIA 1.1 Combo Box Widget with List Autocomplete and Automatic Selection

Fruit:

Example 1 Markup

The markup for this example is as follows:

<div id="cb1-label">Fruit:</div>
<div id="cb1-wrapper" aria-labelledby="cb1-label" class="cb-wrapper" role="combobox" aria-expanded="false" aria-haspopup="true">

   <input id="cb1" type="text" class="cb-edit" aria-autocomplete="both" aria-controls="cb1-list" aria-activedescendant="">
   <div id="cb1-btn" class="cb-btn" role="button" aria-label="Toggle list"></div>

   <span id="cb1-status" role="status" class="cb-status"></span>

   <div id="cb1-list" role="listbox" class="cb-list cb-collapsible" style="display: none;">
      <div id="cb1-opt0" role="option" aria-selected="false">Banana</div>
      <div id="cb1-opt1" role="option" aria-selected="false">Blueberry</div>
      <div id="cb1-opt2" role="option" aria-selected="false">Apple</div>
      <div id="cb1-opt3" role="option" aria-selected="false">Orange</div>
      <div id="cb1-opt4" role="option" aria-selected="false">Strawberry</div>
      <div id="cb1-opt5" role="option" aria-selected="false">Kiwi</div>
      <div id="cb1-opt6" role="option" aria-selected="false">Ugli Fruit</div>
   </div>

</div>

ARIA 1.0 Implementation

Example 2 illustrates a legacy ARIA 1.0 combo box widget with a listbox popup. Authors may implement the legacy ARIA 1.0 combo box pattern until the ARIA 1.1 pattern achieves better support. There are no plans to deprecate the ARIA 1.0 combo box pattern at this time, so it should be safe to use this pattern if wide user agent support is needed.

As with Example 1, this combo box has list autocomplete and automatic selection behavior.

Example 2: ARIA 1.0 Combo Box Widget with List Autocomplete and Automatic Selection

Exotic Fruit:

Example 2 Markup

The markup for Example 2 is as follows:

<div id="cb2-label">Exotic Fruit:</div>
<div id="cb2-wrapper" class="cb-wrapper">

   <input id="cb2" type="text" aria-labelledby="cb2-label" class="cb-edit" role="combobox" aria-controls="cb2-list" aria-owns="cb2-list" aria-autocomplete="both" aria-haspopup="true" aria-expanded="false" aria-activedescendant="">
   <div id="cb2-btn" class="cb-btn" role="button" aria-label="Toggle list"></div>

   <span id="cb2-status" role="status" class="cb-status"></span>

   <div id="cb2-list" role="listbox" class="cb-list cb-collapsible" style="display: none;">
      <div id="cb2-opt0" role="option" aria-selected="false">Chom Chom</div>
      <div id="cb2-opt1" role="option" aria-selected="false">Dragon fruit</div>
      <div id="cb2-opt2" role="option" aria-selected="false">Durian</div>
      <div id="cb2-opt3" role="option" aria-selected="false">Guava</div>
      <div id="cb2-opt4" role="option" aria-selected="false">Jackfruit</div>
      <div id="cb2-opt5" role="option" aria-selected="false">Starfruit</div>
      <div id="cb2-opt6" role="option" aria-selected="false">Persimmon</div>
   </div>

</div>

Keyboard Interaction Pattern

The keyboard interaction pattern for the widget is in Table 1, below.

Table 1: Keyboard Interaction
Key	Function
Tab	Collapse the list box (if expanded), and move focus to next item in the page Tab sequence. Note: The combo box button (if present), the popup, and the options in the popup are excluded from the Tab sequence.
Enter	Choose the currently selected option, collapsing the popup if it is expanded.
Esc	Restore the previously selected option (or clear the textbox if no previous selection), collapsing the popup if it is expanded.
Down Arrow	If the Alt key is pressed, expand the popup If the popup is collapsed and the editbox is empty, expand the popup and select the first option If the popup is collapsed and the editbox has a value, expand the popup and select that option If the popup is expanded, select the next option
Up Arrow	If the Alt key is pressed, collapse the popup If the popup is expanded, select the previous option