Forms & ControlsFlagship guide
Accessible Combobox
A text input combined with a popup listbox that filters/suggests options as the user types.
Last verified against WCAG 2.2 and WAI-ARIA APG 1.2 on 2026-07-02.
Implementation
<label for="fruit">Choose a fruit</label>
<!-- Editable combobox. aria-expanded reflects the popup; aria-controls
points at the listbox; aria-autocomplete="list" says suggestions
appear as you type. aria-activedescendant (set from JS) highlights
an option WITHOUT moving DOM focus off the input, so the caret and
the screen reader's "edit text" mode are preserved. -->
<input
id="fruit"
role="combobox"
aria-expanded="false"
aria-controls="fruit-listbox"
aria-autocomplete="list"
autocomplete="off"
/>
<ul id="fruit-listbox" role="listbox" aria-label="Fruits" hidden></ul>Required roles, states & properties
| Element | Attribute | Why |
|---|---|---|
| Text input | role="combobox" | Identifies the input as a combobox, not a plain textbox, so AT announces "combobox" and exposes expand/collapse state. |
| Text input | aria-expanded | Tells AT whether the suggestion popup is currently open, announced as "collapsed" or "expanded." |
| Text input | aria-controls | Associates the input with the popup listbox it controls, by id. |
| Text input | aria-autocomplete="list" | Tells AT that typing produces a filtered list of suggestions (as opposed to inline text completion). |
| Text input | aria-activedescendant | Points at the id of the currently-highlighted option while DOM focus stays on the input, so the caret and screen reader cursor never leave the edit field. |
| Popup list | role="listbox" | Identifies the popup as a list of selectable options. |
| Each option | role="option" + aria-selected | Identifies each row as selectable and communicates which one is currently active. |
Keyboard interaction model
| Key | Behavior |
|---|---|
| Down Arrow | Opens the popup if closed; otherwise moves the active option to the next item. |
| Up Arrow | Moves the active option to the previous item. |
| Enter | Commits the active option's value into the input and closes the popup. |
| Escape | Closes the popup without changing the input value. |
| Home / End | Moves the active option to the first / last item in the popup. |
| Printable characters | Filters the option list; popup opens automatically. |
Focus management rules
- DOM focus stays on the text input at all times, never moves into the popup.
- The active option is communicated via aria-activedescendant, not real focus.
- Selecting an option (mouse or keyboard) returns focus to the input immediately.
- Closing the popup (Escape or outside click) never moves focus away from the input.
WCAG 2.2 success criteria mapping
| SC | Name | Level | Why it applies |
|---|---|---|---|
| 1.3.1 | Info and Relationships | A | Structure and relationships conveyed visually are also programmatically determinable. |
| 2.1.1 | Keyboard | A | All functionality is operable through a keyboard interface with no specific timing. |
| 2.4.3 | Focus Order | A | Focusable components receive focus in an order that preserves meaning and operability. |
| 3.3.2 | Labels or Instructions | A | Labels or instructions are provided when content requires user input. |
| 4.1.2 | Name, Role, Value | A | For all UI components, name, role, and value are programmatically determinable; states and changes are announced. |