Labeling
- Name the list with
aria-labelledbyoraria-label. The component does not add a name by itself. - Name a
ListboxGroupthe same way.
Keyboard Behavior
AnnouncementFocus the demo and press a key from the table.
| Key | Action |
|---|---|
| Tab | Moves the focus to the list, which makes the selected option, or the first enabled one, active. The list is one tab stop. |
| ↓↑ | Makes the next or previous enabled option active, skipping disabled ones and stopping at the ends. The focus stays on the list. |
| HomeEnd | Makes the first or last enabled option active. |
| Page DownPage Up | Moves the active option 10 options down or up, stopping at the last or first enabled one. |
| p | Typeahead: a printable character makes the next option whose label starts with the typed text active; characters typed quickly add up. Turned off with typeahead={false}. |
| EnterSpace | Selects the active option. With multiple, toggles it and keeps the other selected options. |
Focus Behavior
- The list is one tab stop. On focus the selected option becomes active, or the first available one.
- The focus stays on the list, and options do not take it.
Screen Reader Semantics
- The list renders
role='listbox'andaria-activedescendant, andaria-multiselectablewithmultiple. - Options render
role='option'witharia-selected, andaria-disabledwhen unavailable. - Groups render
role='group'.
Form Semantics
Listboxdoes not submit a value in a form. Keep the value in state and send it yourself, or use Select withSelectHiddenSelect.
Accessibility Risks
- leaving the list or a group without a name
- putting interactive controls inside an option
- relying on
aria-activedescendantwithout testing in the screen readers you support