Listbox

Preview

A listbox lets the user pick from a visible set of options. Its primary job is to make scanning and selection fast in a constrained space (often inside a dropdown panel).

Listbox is commonly used inside Select and as the results panel for Search field.

When to use

Use a listbox when the job is scanning and selecting from a visible set of options, often in a constrained space like a dropdown panel.

It’s a good fit when the option set needs to scroll, or when choices are shown as results under a query (for example in a typeahead under a Search field).

Rules of thumb vs the closest alternatives:

• Listbox vs Select: Use Select for the full “field + trigger + dropdown” pattern. Use Listbox when you already have the trigger/panel pattern and need the option list inside it.
• Listbox vs Search field: If the user types to filter or find items, use Search field and present results using a listbox. If there’s no query and the job is simply choosing from options, use Listbox (often via Select).
• Listbox vs Radio/Checkbox: If there are only a few options and they can stay visible in the layout (roughly 2–6), use Radio (single) or Checkbox (multi). Use Listbox when options need scrolling or live in a compact panel.
• Listbox vs Toggle button group: Use Toggle button group for short, state-like choices that should stay visible as controls (often filters). Use Listbox when the list is long or needs scrolling.
• Listbox vs Tabs: Use Tabs when the selection is navigation between sections/views. Use Listbox when it’s choosing an item or value.

When not to use

• Don’t use Listbox on its own when users expect a field. If the list is opened from a trigger or needs a label, validation, and form semantics, use Select.
• Don’t use it for navigation (page changes, routes, “go to …”). Use Tabs or a list of links (Link).
• Don’t use it for rich option layouts. If each option needs long descriptions, images, or multiple actions, Listbox becomes hard to scan and hard to operate by keyboard. Use a list/cards pattern instead.
• Don’t use it for binary choices. Use Switch or a single Checkbox.

Behaviour

Listbox supports single selection and multiple selection.

• Single selection: selecting an option makes it the only selected option.
• Multiple selection: selecting an option toggles that option on/off without affecting the others.

Whether “none selected” is allowed depends on the surrounding pattern:

• Allowed when the selection is optional (for example a filter list that can be cleared, or a Select that starts empty with a placeholder).
• Not allowed when exactly one option must always be selected (for example a required setting with a default).

Keyboard and assistive tech requirements (pattern-level, cross-platform):

• Reachability: the user can reach the listbox and every enabled option with a keyboard.
• Operation: the user can move between options with arrow keys and select with Space or Enter.
• Name/role/state: the listbox has a programmatic label, options expose their selected state, and multi-select is communicated as multi-select.

Disabled options:

• A disabled option is visible but cannot be selected.
• Disabled options should not take focus during keyboard navigation (so users don’t have to “tab through” unavailable choices).

Async selection (when selecting triggers loading or a server update):

• Treat selection as a state change that can fail. Don’t show a successful state if the change didn’t persist.
• If the update fails, keep the UI predictable: revert to the previous selection (or clearly keep the option unselected) and give feedback near the control.

Anatomy

• Listbox: the container that holds the options and handles keyboard navigation.
• Option: a selectable row representing one choice.
• Option label: the primary text for the option.
• Selection state: the option is either selected or not selected (single or multi).
• Optional leading icon: used when an icon helps the user recognise options faster.

Variants

• Single-select listbox: choose exactly one option at a time.
• Multi-select listbox: choose any number of options.
• With leading icons: options include a leading icon (use only when the icon adds meaning).
• In a dropdown panel: used inside Select or under a Search field.

States

Placement & layout

• Constrain height. Prefer a maximum height with internal scroll, so the listbox doesn’t take over the page.
• Align with its trigger when used under a Select or Search field. The panel should feel connected to the control that opened it.
• Keep the panel readable. If you need a constraint, a suggested maximum width is around 480px (wide enough for most option labels without creating a “long line” scan). Go wider when the content genuinely needs it (for example long place names or product titles).
• Avoid viewport collisions. Don’t let the panel extend beyond the viewport; flip or resize the panel when needed.
• Keep options scannable. Aim for one clear line per option. If labels regularly wrap to multiple lines, the set is probably too dense for a listbox.

Content guidance for options:

• Write options as options, not states. Prefer “Delivery” over “Delivered”, “Vegetarian” over “Is vegetarian”.
• Keep grammar consistent across the list (all nouns, or all verbs).
• Avoid negations like “Not selected” or “Don’t include …” as option labels; they’re easy to misread in a scan.
• Use icons sparingly. If every option needs an icon to be understood, the labels are probably too vague.
• Avoid badges and long supporting text inside options. If users need extra explanation per item, Listbox is usually the wrong pattern.

Related components

• Select — the full “field + dropdown” pattern for choosing from a listbox.
• Search field — for filtering/finding items; can present results using a listbox.
• Radio — for single choice when all options can stay visible (no scrolling).
• Checkbox — for multi-select when options should stay visible inline in a form.
• Toggle button group — for short, state-like choices (often filters) that should stay visible.
• Tabs — for switching views/sections (navigation-like selection).