Listbox

Problem Context

• The available values should remain visible while users choose.
• Options are static enough to be represented as selectable choices rather than interactive row content.
• Users need keyboard movement through options and a perceivable selected state.
• The list may be long enough for typeahead, scrolling, Home and End, or grouping.
• The product must decide whether moving focus only previews an option or also selects it.

Selection Rules

• Choose a listbox when options should remain visible and users select one or more values from the list itself.
• Use a native select when a compact closed single-choice control is sufficient.
• Use a combobox when the list is a popup controlled by an input or button and the field value owns the interaction.
• Use radio buttons or checkbox groups when the set is short and normal form controls communicate the job with less custom keyboard work.
• Use multi-select when the product pattern is a compact searchable picker with selected chips or a selected-set review surface.
• Use a grid, table, menu, or separate action toolbar when rows need buttons, links, checkboxes, toggles, or editable controls.
• Keep option names short and move repeated category context into group labels or separate controls.
• Make selection-follows-focus opt-in for low-risk preview contexts and avoid it for destructive, expensive, or externally visible changes.

Required States

• Empty or initial state with visible label and at least one option.
• Focused listbox state.
• Active option state distinct from selected state.
• Selected option state.
• Selection-follows-focus enabled or disabled policy state.
• Typeahead matched option state.
• First option and last option states for Home and End movement.
• Disabled option state.
• Read-only listbox state.
• Required no-selection validation state.
• Grouped options state when categories are present.
• Scrollable long-list state with preserved active visibility.

Interaction Contract

• The listbox has a visible label or accessible name and contains or owns every option.
• Each selectable option exposes one selected state using aria-selected or aria-checked consistently.
• Active focus is represented by DOM focus on an option or by aria-activedescendant on the listbox.
• Arrow keys move the active option; Home and End move to list boundaries when supported.
• Typeahead moves focus to the next option whose name starts with the typed character sequence.
• Single-select listboxes select at most one option; multi-select listboxes set aria-multiselectable and expose state on every selectable option.
• Moving focus changes selection only when the interaction model explicitly uses selection-follows-focus.
• Options are not containers for independent interactive controls.

Implementation Checklist

• Confirm that users need a visible custom option list instead of native select, radio buttons, checkbox groups, combobox, or multi-select picker.
• Choose single-select or multi-select and document whether selection follows focus.
• Use role listbox on the container and role option on each option, or use a native control that exposes equivalent semantics.
• Give the listbox a visible label with aria-labelledby or an accessible name with aria-label.
• Use aria-activedescendant or roving DOM focus consistently and keep the active option in view.
• Expose aria-selected or aria-checked consistently, and set aria-multiselectable for multi-select lists.
• Implement Arrow keys, Home, End, typeahead, Space or Enter selection, required validation, disabled options, and read-only state.
• Move interactive row actions outside the listbox or choose a grid or table pattern.
• Test keyboard, screen reader, touch, high zoom, forced colors, long option names, repeated prefixes, grouping, scrolling, and dynamic option updates.

Common Generated-UI Mistakes

• Using listbox when native select, radio buttons, or checkboxes would do the job with less risk.
• Putting buttons, links, checkboxes, toggles, menus, or form fields inside options.
• Treating focus and selection as identical without deciding whether selection follows focus.
• Using long repeated option labels that hide the distinguishing words.
• Leaving aria-activedescendant pointing to a removed or hidden option.
• Failing to expose unselected state in a multi-select listbox.
• Using a listbox as a command menu where options trigger actions instead of setting a value.

Critique Questions

• Do users need the options visible all the time, or is this really a select or combobox?
• Is focus movement separate from selection, and is that policy visible in the UI?
• Are all option names short enough to be understood as one spoken string?
• Do any options contain interactive controls that require a grid, table, menu, or toolbar instead?
• Can keyboard users reach the first option, last option, a typed prefix, disabled options, and validation errors predictably?