Listbox

A listbox presents a scrollable list of options and lets users select one or more items using full keyboard navigation and clear selection state.

Demo

Tab into the listbox below and use the Up Arrow and Down Arrow keys to move through the options. Press Space or Enter to select the focused option. In a multi-select listbox, hold Shift while using arrow keys to extend the selection, or use Ctrl + Space to toggle individual items. Observe how focus, selection, and state changes are communicated.

Choose Toppings

Select one or more toppings. Use Space to toggle, Shift+Arrow to select a range, Ctrl+A to select all.

What to Observe

The listbox receives a single tab stop — internal navigation between options uses arrow keys, not the Tab key.
The focused option is visually distinct and announced by screen readers as the current item moves through the list.
Selected options communicate their state via aria-selected="true", which screen readers announce when the option gains focus.
The listbox has an accessible name (from a visible label or aria-labelledby) so screen readers announce what the list is for.
In a multi-select variant, the number of selected items is communicated to assistive technology as selections change.

Anatomy

[Anatomy image placeholder — will be added when assets are available]

Label — A visible label or heading associated with the listbox that tells users what they are selecting from.
Listbox container — The element with role="listbox" that receives keyboard focus and wraps all options.
Options — Individual items with role="option" and an aria-selected attribute reflecting their current selection state.
Focus indicator — A visible highlight on the currently focused option, distinct from the selection highlight.
Selection indicator — A visual treatment (checkmark, background color, or similar) applied to all currently selected options.

Accessibility Behavior

The listbox container must have role="listbox" and be labeled via a visible <label>, aria-labelledby, or aria-label.
Each option must have role="option" and an aria-selected attribute that accurately reflects whether it is currently selected.
The listbox must accept a single tab stop, with arrow keys used to navigate between options.
The currently focused option must be tracked via aria-activedescendant on the listbox element, or by moving DOM focus to each option directly.
For multi-select listboxes, the component must carry aria-multiselectable="true" and support standard multi-select keyboard patterns.
Selection changes must be announced to screen readers immediately, either through the option's aria-selected state or a supplemental live region.

Common Mistakes

Building the list with plain <li> elements and click handlers without any ARIA roles, making it invisible and inoperable for assistive technology.
Allowing Tab to navigate between options instead of arrow keys, which breaks the expected interaction model and causes each option to become a separate tab stop.
Setting aria-selected only on the focused option instead of all selected options, causing the selection state to appear to follow focus rather than persist.
Omitting a label for the listbox, so screen readers announce it as an unlabeled list with no context.
Using a listbox for a task better suited to a native <select> element, adding complexity without accessibility benefit.

Why This Matters

Listboxes are used in scenarios where a native <select> is insufficient — such as multi-select with rich content, reorderable lists, or custom styling requirements. When a custom listbox fails to implement the correct ARIA roles and keyboard patterns, screen reader users encounter a list that appears non-interactive, and keyboard-only users cannot select items at all. Because listboxes are often used for consequential selections — assigning permissions, choosing recipients, or filtering large datasets — inaccessibility here can block users from completing high-priority tasks entirely.

Accessibility Validation

This component is validated against internal accessibility criteria aligned with WCAG standards, using our internally developed system, Resonance Specs.

To learn more, please contact us.