WAI-ARIA: Role=Combobox

A composite widget containing a single-line textbox and another element such as listbox or grid, that can dynamically pop up to help the user set the value of the textbox.

Description

A composite widget containing a single-line textbox and another element, such as a listbox or grid, that can dynamically pop up to help the user set the value of the textbox.

Authors MUST ensure an element with role combobox contains or owns a text input element with role textbox or searchbox and that the text input has aria-multiline set to false. If the combobox provides autocompletion behavior for the text input as described in aria-autocomplete, authors MUST set aria-autocomplete on the textbox element to the value that corresponds to the provided behavior.

Typically, the default state of a combobox is collapsed. In the collapsed state, only the textbox element of a combobox is visible. A combobox is said to be expanded when both the textbox and a secondary element that serves as its popup are visible. Authors MUST set aria-expanded to true on an element with role combobox when it is expanded and false when it is collapsed. Elements with the role combobox have an implicit aria-expanded value of false.

When a combobox is expanded, authors MUST ensure it contains or owns an element that has a role of listbox, tree, grid, or dialog. This element is the combobox popup. When the combobox is expanded, authors MUST set aria-controls on the textbox element to a value that refers to the combobox popup element.

Elements with the role combobox have an implicit aria-haspopup value of listbox. If the combobox popup element has a role other than listbox, authors MUST specify a value for aria-haspopup that corresponds to the type of its popup.

To be keyboard accessible, authors SHOULD manage focus of descendants for all instances of this role, as described in Managing Focus. When a combobox receives focus, authors SHOULD ensure focus is placed on the textbox element.

Authors SHOULD provide keyboard mechanisms for moving focus between the textbox element and the elements contained in the popup. For example, one common convention is that Down Arrow moves focus from the text input to the first focusable descendant of the popup element. If the popup element supports aria-activedescendant, in lieu of moving focus, such keyboard mechanisms can control the value of aria-activedescendant on the textbox element. When a descendant of the popup element is active, authors MAY set aria-activedescendant on the textbox to a value that refers to the active element within the popup while focus remains on the textbox element.

The ARIA 1.0 specification describes a combobox pattern where a text input element has the combobox role and owns a listbox element. User agents, assistive technologies, and conformance checkers SHOULD continue to support the ARIA 1.0 pattern so that existing implementations of the ARIA 1.0 pattern remain functional.

The features and behaviors of combobox implementations vary widely. Consequently, there are many important authoring considerations. See the WAI-ARIA Authoring Practices Guide [wai-aria-practices-1.1] for additional details on implementing combobox design patterns.

Screen Reader Support For Role=ComboBox

Role=Combobox Example

HTML Example

<div aria-label="Tag" role="combobox" aria-expanded="true" aria-owns="owned_listbox" aria-haspopup="listbox"><input type="text" aria-autocomplete="list" aria-controls="owned_listbox" aria-activedescendant="selected_option"></div><ul role="listbox" id="owned_listbox"><li role="option">Zebra</li><li role="option" id="selected_option">Zoom</li></ul>

HTML Example 2

A page contains a combobox composed of a textbox and a dropdown list of values which the user may choose from. The chosen list item becomes the value of the textbox. As the user navigates through the list via arrow keys, the aria-activedescendant property is adjusted to reflect the id attribute of the current child element which has been navigated to.

<input type="text" aria-activedescendant="cb1-opt6" aria-readonly="true" aria-owns="cb1-list" aria-autocomplete="list">
<ul aria-expanded="true" role="listbox" id="cb1-list">
  <li role="option" id="cb1-opt1">Alabama</li>
  <li role="option" id="cb1-opt2">Alaska</li>
  <li role="option" id="cb1-opt3">American Samoa</li>
  <li role="option" id="cb1-opt4">Arizona</li>
  <li role="option" id="cb1-opt5">Arkansas</li>
  <li role="option" id="cb1-opt6">California</li>
  <li role="option" id="cb1-opt7">Colorado</li>
</ul>

Characteristics

Superclass Role

• select

Related Concepts

• HTML select
• XForms select

Required Owned Elements

• textbox and, when expanded, one of:
  • listbox
  • tree
  • grid
  • dialog

Required States and Properties

• aria-controls
• aria-expanded

Supported States and Properties

• aria-autocomplete
• aria-readonly
• aria-required

Inherited States and Properties:

• aria-activedescendant
• aria-atomic
• aria-busy (state)
• aria-current (state)
• aria-describedby
• aria-details
• aria-disabled (state)
• aria-dropeffect
• aria-errormessage
• aria-flowto
• aria-grabbed (state)
• aria-haspopup
• aria-hidden (state)
• aria-invalid (state)
• aria-keyshortcuts
• aria-label
• aria-labelledby
• aria-live
• aria-orientation
• aria-owns
• aria-relevant
• aria-roledescription

Name From

• author

Accessible Name Required

• True

Implicit Value for Role

• Default for aria-expanded is false.
• Default for aria-haspopup is listbox.

Semantic HTML

Use the HTML <select> tag.

<select>
<option value="volvo">Volvo</option>
<option value="saab">Saab</option>
<option value="mercedes">Mercedes</option>
<option value="audi">Audi</option>
</select>

Reference

• WAI-ARIA 1.2 Specification
  Refer to the notes from the WAI-ARIA 1.2 specification for more information on role=combobox.
• A11Y Support
  The screenreader compatibility for each of the ARIA attributes is taken from the A11Y Support. Please refer to the original source if screenreader compatibility is updated for role=combobox.