Developer Playground

20+ Free Tools · Privacy First

ARIA ROLE•Composite RolesSingle & multi-selectTypeahead friendlyPair with combobox

`listbox`

A scrollable list of options that lets people choose one or multiple values. Listboxes often power custom selects or filter pickers.

Live Example

Command Listbox

Single-select listbox with roving focus, arrow keys, Home/End, and selection announcement.

Choose a section

Selected: Dashboard

Purpose

Provide a flexible replacement for native select elements with richer styling and behavior.

Focus model

Usually keeps DOM focus inside the listbox and roves active option with tabindex.

Screen Reader

Announces position (1 of N) and selected state while supporting letter navigation.

When to Use

Filter builders

Allow people to pick multiple facets (tags, categories, permissions) quickly.

Enhanced selects

Style default pickers, add icons, group options, or show meta data.

Combo popup

Act as the suggestion surface inside a combobox or menu button.

Required Structure

Container

role="listbox" element needs an accessible name via aria-label or aria-labelledby.

Options

Direct children must use role="option" (or be wrapped in group elements that contain options).

Selection State

Use aria-selected to reflect the actual selection. Update it immediately when state changes.

Keyboard Interaction Model

Action	Keys	Result
Move focus	`ArrowUp / ArrowDown`	Moves between options while keeping focus inside the listbox.
Jump to edges	`Home / End`	Moves to the first or last option.
Select option	`Space / Enter`	Toggles aria-selected on the focused option.
Range selection	`Shift + Arrow / Shift + Space`	Extends the selection when aria-multiselectable is true.
Typeahead	`Printable characters`	Focuses the next option whose text matches the typed characters.

Required States & Properties

aria-label / aria-labelledbyRequired

Provides an accessible name for the listbox. Required when no visible label is present.

aria-activedescendantOptional

Alternative to roving tabindex. Reference the id of the focused option.

aria-multiselectableOptional

Set to true to indicate multiple selections are allowed.

aria-requiredOptional

Communicates that the user must pick an option before submitting.

aria-describedbyOptional

Point to helper text explaining keyboard shortcuts or selection behavior.

Implementation Checklist

✓
If you wrap options in custom markup, ensure the element with role="option" receives aria-selected and tabindex.
✓
Keep the focused option visible (scroll into view) so keyboard users always know their position.
✓
When used as part of a combobox, hide the listbox visually but keep it mounted the entire time.
✓
Use aria-live or status text to confirm selections in multi-select scenarios when the list is long.
✓
Mirror selection state visually with strong contrast for selected options.

Code Examples

Single-Select Listbox

Roving tabindex ensures only the focused option is in the tab order.

<div role="listbox" aria-label="Project status" id="status-listbox">
  <div role="option" id="status-1" tabindex="0" aria-selected="true">Not Started</div>
  <div role="option" id="status-2" tabindex="-1" aria-selected="false">In Progress</div>
  <div role="option" id="status-3" tabindex="-1" aria-selected="false">Blocked</div>
  <div role="option" id="status-4" tabindex="-1" aria-selected="false">Complete</div>
</div>

Multi-Select with Instructions

aria-multiselectable announces that multiple values can be toggled.

<p id="filter-hint">Use Space to toggle and Shift+Arrow for range selection.</p>
<div
  role="listbox"
  aria-multiselectable="true"
  aria-labelledby="filters-label"
  aria-describedby="filter-hint"
>
  <span id="filters-label" class="sr-only">Filter by topics</span>
  <div role="option" aria-selected="true" tabindex="0">Performance</div>
  <div role="option" aria-selected="false" tabindex="-1">Security</div>
  <div role="option" aria-selected="false" tabindex="-1">Accessibility</div>
  <div role="option" aria-selected="true" tabindex="-1">DevOps</div>
</div>

Best Practices

ℹ️

Describe selection mode

Explain whether users can choose one or many items and which modifiers to use.

🆔

Stable option ids

Keep id attributes stable so aria-activedescendant references remain valid when filtering.

🖱️

Sync pointer + keyboard

Clicking an option should also update tabindex and aria-selected.

Common Mistakes

Using buttons inside listbox

Buttons inside the list steal focus and break arrow navigation.

Keep options focusable elements and nest button-like UI inside using aria-hidden.

Forgetting aria-selected

Users cannot determine which items were chosen, especially in multi-select lists.

Toggle aria-selected immediately whenever selection state changes.

Related Roles & Patterns

option

The selectable child role inside a listbox.

Learn more

combobox

Editable widget that commonly controls a listbox popup.