Combobox

Purpose

A combobox combines a text input with an associated dropdown list. It allows users to either type a value or select from a predefined set of options, with optional filtering.

Usage Guidance

• Use when there are too many options for a radio group or standard select
• Provide a clear label indicating what should be entered or selected
• Support both keyboard entry and list selection
• Consider whether an autocomplete behavior is appropriate

Accessibility Considerations

• Follow the ARIA combobox pattern (APG): the input has role="combobox"
• The associated listbox has role="listbox" and each option has role="option"
• aria-expanded on the input reflects whether the listbox is visible
• aria-controls on the input references the listbox id
• aria-activedescendant on the input references the focused option’s id

Keyboard Support

Screen Reader Behavior

Screen readers announce the input label, “combobox” role, and whether it is expanded. As the user navigates options, each option label is announced via aria-activedescendant.

ARIA Requirements

• role="combobox" on the <input>
• aria-expanded="true|false" on the <input>
• aria-controls="listbox-id" on the <input>
• aria-activedescendant="option-id" on the <input> (when an option is focused)
• role="listbox" on the dropdown container
• role="option" on each list item
• aria-selected="true" on the currently selected option

Common Mistakes

• Using a custom combobox when a native <select> would suffice
• Not updating aria-activedescendant during keyboard navigation
• Hiding the listbox with display:none without updating aria-expanded
• Poor focus management when the listbox closes

Live Example

Code Pattern

<label for="combobox-input">Search criteria</label>
<div class="combobox-wrapper">
  <input
    id="combobox-input"
    role="combobox"
    type="text"
    aria-expanded="false"
    aria-controls="combobox-list"
    aria-autocomplete="list"
    aria-activedescendant=""
    autocomplete="off"
  >
  <ul id="combobox-list" role="listbox" hidden>
    <li id="opt-1" role="option" aria-selected="false">Option 1</li>
    <li id="opt-2" role="option" aria-selected="false">Option 2</li>
  </ul>
</div>