In-depth Guides
Angular Aria

Listbox

Overview

A directive that displays a list of options for users to select from, supporting keyboard navigation, single or multiple selection, and screen reader support.

Usage

Listbox is a foundational directive used by the Select, Multiselect, and Autocomplete patterns. For most dropdown needs, use those documented patterns instead.

Consider using listbox directly when:

  • Building custom selection components - Creating specialized interfaces with specific behavior
  • Visible selection lists - Displaying selectable items directly on the page (not in dropdowns)
  • Custom integration patterns - Integrating with unique popup or layout requirements

Avoid listbox when:

  • Navigation menus are needed - Use the Menu directive for actions and commands

Features

Angular's listbox provides a fully accessible list implementation with:

  • Keyboard Navigation - Navigate options with arrow keys, select with Enter or Space
  • Screen Reader Support - Built-in ARIA attributes including role="listbox"
  • Single or Multiple Selection - multi attribute controls selection mode
  • Horizontal or Vertical - orientation attribute for layout direction
  • Type-ahead Search - Type characters to jump to matching options
  • Signal-Based Reactivity - Reactive state management using Angular signals

Examples

Basic listbox

Applications sometimes need selectable lists visible directly on the page rather than hidden in a dropdown. A standalone listbox provides keyboard navigation and selection for these visible list interfaces.

The values model signal provides two-way binding to the selected items. With selectionMode="explicit", users press Space or Enter to select options. For dropdown patterns that combine listbox with combobox and overlay positioning, see the Select pattern.

Horizontal listbox

Lists sometimes work better horizontally, such as toolbar-like interfaces or tab-style selections. The orientation attribute changes both the layout and keyboard navigation direction.

With orientation="horizontal", left and right arrow keys navigate between options instead of up and down. The listbox automatically handles right-to-left (RTL) languages by reversing navigation direction.

Selection modes

Listbox supports two selection modes that control when items become selected. Choose the mode that matches your interface's interaction pattern.

The 'follow' mode automatically selects the focused item, providing faster interaction when selection changes frequently. The 'explicit' mode requires Space or Enter to confirm selection, preventing accidental changes while navigating. Dropdown patterns typically use 'follow' mode for single selection.

APIs

Listbox Directive

The ngListbox directive creates an accessible list of selectable options.

Inputs

Property Type Default Description
id string auto Unique identifier for the listbox
multi boolean false Enables multiple selection
orientation 'vertical' | 'horizontal' 'vertical' Layout direction of the list
wrap boolean true Whether focus wraps at list edges
selectionMode 'follow' | 'explicit' 'follow' How selection is triggered
focusMode 'roving' | 'activedescendant' 'roving' Focus management strategy
softDisabled boolean true Whether disabled items are focusable
disabled boolean false Disables the entire listbox
readonly boolean false Makes listbox readonly
typeaheadDelay number 500 Milliseconds before type-ahead search resets

Model

Property Type Description
values V[] Two-way bindable array of selected values

Signals

Property Type Description
values Signal<V[]> Currently selected values as a signal

Methods

Method Parameters Description
scrollActiveItemIntoView options?: ScrollIntoViewOptions Scrolls the active item into view
gotoFirst none Navigates to the first item in the listbox

Option Directive

The ngOption directive marks an item within a listbox.

Inputs

Property Type Default Description
id string auto Unique identifier for the option
value V - The value associated with this option (required)
label string - Optional label for screen readers
disabled boolean false Whether this option is disabled

Signals

Property Type Description
selected Signal<boolean> Whether this option is selected
active Signal<boolean> Whether this option has focus

Listbox is used by these documented dropdown patterns:

  • Select - Single-selection dropdown pattern using readonly combobox + listbox
  • Multiselect - Multiple-selection dropdown pattern using readonly combobox + listbox with multi
  • Autocomplete - Filterable dropdown pattern using combobox + listbox

For complete dropdown patterns with trigger, popup, and overlay positioning, see those pattern guides instead of using listbox alone.