Type to filter — the list of matches under the field is the listbox popup
Combobox (Autocomplete / Typeahead)
/ role="combobox" · role="listbox" /
also called autocomplete, typeahead, search select, editable dropdown
A combobox combines an editable text field with a popup list of matching values. Typing narrows the choices while arrow keys move the active option and Enter commits it. Unlike a plain select, it supports searching or free-form input depending on the product rules.
If you called it…
…you meant a combobox (autocomplete / typeahead).
Anatomy — every part, named
- 1Combobox input
role="combobox"“The searchable dropdown field I type into” is the combobox input.
- 2Listbox popup
role="listbox"“The matching results underneath the field” are the listbox popup.
- 3Active option
aria-activedescendant“The result highlighted as I press the arrow keys” is the active option.
- 4Selected-option checkmark
aria-selected“The checkmark next to the choice I already picked” is the selected-option indicator.
Prompt — paste into your agent
Build a labelled Combobox with role="combobox" and a controlled role="listbox" popup. Keep aria-expanded and aria-controls in sync, give each result role="option", retain DOM focus in the input with aria-activedescendant, and support Arrow keys, Enter, and Escape without autofocusing on mount.
Debug prompt — when it misbehaves
Paste this, then describe what you’re seeing — it hands your agent the classic failure modes to rule out first.
Debug my combobox (role=combobox, aria-activedescendant, cmdk/Radix). Rule out: the listbox closing on blur before the option click lands — handle selection on pointerdown or check relatedTarget; the highlighted index not resetting when the filter changes; aria-activedescendant pointing at a filtered-out option id; the mobile keyboard covering the list because nothing scrolls the field into view. The symptom:
In code
The exact names this thing goes by in code — each row is one framework’s word for it. Use the row that matches your project (or paste it into your prompt).
| ARIA | role="combobox" | |
| ARIA | role="listbox" | |
| ARIA | aria-expanded | |
| ARIA | aria-controls | |
| ARIA | aria-activedescendant | |
| HTML | <datalist> | a native limited alternative |