Guide
Accessibility
The widget follows the WAI-ARIA Authoring Practices combobox pattern, and the browser tests assert it — roles, keys and all.
Roles and state
| Element | Role | Carries |
|---|---|---|
| The text field | combobox |
aria-expanded, aria-controls, aria-haspopup="listbox", aria-autocomplete="list", aria-activedescendant |
| The list | listbox |
aria-label, aria-multiselectable when multiple |
| Each row | option |
aria-selected, aria-disabled, aria-label (the label, plus its group when grouped) |
| A live region | status |
"6 results", "Pakistan selected", "You can choose 2" |
Focus never leaves the text field: the active row is pointed at with aria-activedescendant, which is
what screen readers expect from a combobox and what keeps typing working.
Keyboard
| Key | Does |
|---|---|
| ↓ / ↑ | Open, then move through the options, skipping disabled ones. |
| Home / End | First and last option. |
| PageDown / PageUp | Ten at a time. |
| Enter | Choose the active option, or create the typed text. |
| Escape | Close, leaving the value alone. |
| Tab | Close and move on — or finish a tag, when separators includes 'Tab'. |
| Backspace | With the field empty and chips present, removes the last chip. |
| Letters | Filter. Without a search box, they type-ahead to the first match, like a native <select>. |
Labels
Enhancing a <select> keeps its label: the <label for> still points at a control in the form, and the
original's aria-* attributes stay on it. Give a standalone widget its own label with aria-label or
aria-labelledby on the element you enhance.
Beyond ARIA
- Touch. Phones get a bottom sheet with 44px rows and its own search box, instead of a dropdown pinned to a field near the keyboard.
- Forced colours. Borders, the active row and highlights are drawn with system colours in
forced-colorsmode. - Reduced motion. The sheet animation and the chevron transition are dropped when the visitor asks for less movement.
- Zoom and long labels. Rows wrap with ellipsis, and the panel is measured against the viewport, so 400% zoom keeps it on screen.
Updated 12 Sep 2026