Listbox
A listbox is a custom list of choices. It manages which choice is active and how arrow keys move through the list.
A real example
A dispatcher picks one depot from 180 searchable results. Arrow keys move through choices, and Enter picks one. After filtering, a screen reader still announces the chosen depot. A short fixed list should use a built-in `<select>` instead.
Main parts
- 01Listbox container
- 02Active option
- 03Selection state
Use it when
Build a custom listbox only when a built-in `<select>` cannot handle search, rich choices, or picking several items.
Do not use it when
Do not put buttons, links, or other separate controls inside an option.
Name used in code
role=listbox + role=option + aria-selected + roving focus/aria-activedescendant Before you ship
Give each field a label that code can read. Link hints and errors, and keep entered values. Check autofill, keyboard order, validation timing, submit states, failure recovery, zoom, and languages.
Outcome: Use Listbox to solve this user need without losing the current context. User context: A dispatcher picks one depot from 180 searchable results. Arrow keys move through choices, and Enter picks one. After filtering, a screen reader still announces the chosen depot. A short fixed list should use a built-in `<select>` instead. Recommended pattern: Listbox. Why it fits: Build a custom listbox only when a built-in `<select>` cannot handle search, rich choices, or picking several items. Do not use it when: Do not put buttons, links, or other separate controls inside an option. Product requirements: Define the default, loading, empty, error, success, and recovery states. Keep user input. Give clear feedback after every action. Accessibility and resilience: Use semantic HTML, full keyboard access, and visible focus. Make the layout work when zoomed and support reduced motion. Follow the project’s current rules. Do not add a new UI library unless the project already uses it. Acceptance criteria: The main task works with keyboard only and at 320px width. Focus and status changes are announced. Check loading, failure, retry, cancel, and reduced-motion paths. Evidence and limits (evidence boundary): It is official for that source. Other platforms or teams may use the term in another way. Unknowns to confirm: Product wording, data source, analytics events, supported devices and languages, and platform limits.
Check this request
Review the current use of Listbox. Definition: A listbox is a custom list of choices. It manages which choice is active and how arrow keys move through the list. Release checks: Give each field a label that code can read. Link hints and errors, and keep entered values. Check autofill, keyboard order, validation timing, submit states, failure recovery, zoom, and languages. Before changing code, report the evidence you found, gaps, severity, and the smallest safe fix.