ARIA combobox pattern

The combobox pattern combines a single-line text input with a popup listbox, tree, grid, or dialog. The 1.2 spec requires aria-expanded, aria-controls, and either aria-activedescendant or focus-managed selection.

Normative spec: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
Last verified: 2026-04-27
Byline: Editorial team

What a combobox is

A combobox is a composite widget: an input element coupled to a popup that displays a set of values to choose from. The popup may be a listbox (most common), a grid (table-laid-out options), a tree (hierarchical options), or a dialog (rare; for richer pickers).

The HTML <select> element is not an ARIA combobox; it is a listbox bound to a button. ARIA’s combobox pattern targets custom text-input-with-suggestions widgets — the address-search field, the tag picker, the country selector with type-ahead.

The 1.2 pattern (post-2020)

ARIA 1.2 (2023 Recommendation) reworked the combobox pattern. The old 1.1 pattern wrapped the input in a role="combobox" div; the 1.2 pattern puts role="combobox" on the input itself.

<label for="cb">Country</label>
<input
  id="cb"
  role="combobox"
  type="text"
  aria-expanded="false"
  aria-controls="lb"
  aria-autocomplete="list"
  aria-activedescendant=""
/>
<ul id="lb" role="listbox" hidden>
  <li id="o1" role="option">Argentina</li>
  <li id="o2" role="option">Brazil</li>
  <li id="o3" role="option">Chile</li>
</ul>

The required ARIA pieces:

role="combobox" on the input.
aria-expanded="true" while the popup is visible, "false" when hidden.
aria-controls referencing the popup’s id.
aria-autocomplete declaring how typing affects the popup (none, inline, list, or both).
Either aria-activedescendant (preferred for combobox) pointing to the currently visible option, or DOM focus on the option.

The popup’s elements have role="option", role="treeitem", etc., matching the popup type.

Selection management: `aria-activedescendant` vs DOM focus

Combobox is one of the two patterns where aria-activedescendant is preferred over moving DOM focus into the popup. The argument:

Focus stays in the input, so the user can keep typing.
The “active” option visually indicated by selection styling is programmatically announced because aria-activedescendant points to it.
Pressing Enter or Tab dismisses the popup and commits the active option.

Moving DOM focus into the listbox is permitted (used in some designs to allow arrow-keys-only navigation) but the user can no longer type. About 70% of well-known combobox implementations (Material UI, Reach UI, Adobe Spectrum) use the aria-activedescendant pattern.

Keyboard interactions

Key	Effect
Down Arrow	Open popup (if closed) and move active option to first; if open, move to next.
Up Arrow	Open popup (if closed) and move to last; if open, move to previous.
Enter	Commit the active option, close the popup.
Escape	Close the popup; first press clears active, second press clears the input.
Tab	Move focus out of the combobox; commit the active option if any.
Home / End	Move active to first / last option.
Type-ahead	Filter or auto-suggest, depending on `aria-autocomplete` value.

These match APG combobox pattern §4.

Common pitfalls

Forgetting to update aria-expanded. Open and close the popup via the property; never style-only-hide.
aria-activedescendant referencing a non-visible option. When the popup is filtered, the descendant must reference an option in the visible set.
Using role="textbox" instead of role="combobox". AT announces the wrong role; the user gets no popup-state cue.
Closing the popup on every input change. Re-open it as the user types; close it only on Escape, Enter, blur, or selection.
Multi-select combobox without an explicit pattern. ARIA 1.2 reserves a multi-select combobox sub-pattern with aria-multiselectable. About 40% of multi-select pickers do this wrong by omitting aria-multiselectable from the popup.

Cross-engine support

The 1.2 pattern reached interop in 2023 across Chromium (Blink), WebKit, and Gecko per Web Platform Tests for ARIA. Older AT (JAWS 2020 and earlier) may still expect the 1.1 wrapper pattern; the editorial recommendation is to author the 1.2 pattern and let AT versions older than 4 years gracefully degrade.