adev/src/content/guide/aria/listbox.md
A directive that displays a list of options for users to select from, supporting keyboard navigation, single or multiple selection, and screen reader support.
<docs-tab-group> <docs-tab label="Basic"> <docs-code-multifile preview hideCode path="adev/src/content/examples/aria/listbox/src/basic/app/app.ts"> <docs-code header="app.ts" path="adev/src/content/examples/aria/listbox/src/basic/app/app.ts"/> <docs-code header="app.html" path="adev/src/content/examples/aria/listbox/src/basic/app/app.html"/> <docs-code header="app.css" path="adev/src/content/examples/aria/listbox/src/basic/app/app.css"/> </docs-code-multifile> </docs-tab> <docs-tab label="Material"> <docs-code-multifile preview hideCode path="adev/src/content/examples/aria/listbox/src/basic/material/app/app.ts"> <docs-code header="app.ts" path="adev/src/content/examples/aria/listbox/src/basic/material/app/app.ts"/> <docs-code header="app.html" path="adev/src/content/examples/aria/listbox/src/basic/material/app/app.html"/> <docs-code header="app.css" path="adev/src/content/examples/aria/listbox/src/basic/material/app/app.css"/> </docs-code-multifile> </docs-tab> <docs-tab label="Retro"> <docs-code-multifile preview hideCode path="adev/src/content/examples/aria/listbox/src/basic/retro/app/app.ts"> <docs-code header="app.ts" path="adev/src/content/examples/aria/listbox/src/basic/retro/app/app.ts"/> <docs-code header="app.html" path="adev/src/content/examples/aria/listbox/src/basic/retro/app/app.html"/> <docs-code header="app.css" path="adev/src/content/examples/aria/listbox/src/basic/retro/app/app.css"/> </docs-code-multifile> </docs-tab> </docs-tab-group>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:
Avoid listbox when:
Angular's listbox provides a fully accessible list implementation with:
multi attribute controls selection modeorientation attribute for layout directionApplications 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.
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/listbox/src/basic/app/app.ts"> <docs-code header="app.ts" path="adev/src/content/examples/aria/listbox/src/basic/app/app.ts" /> <docs-code header="app.html" path="adev/src/content/examples/aria/listbox/src/basic/app/app.html" /> </docs-code-multifile>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.
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.
Listbox supports two selection modes that control when items become selected.
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.
| Mode | Description |
|---|---|
'follow' | Automatically selects the focused item, providing faster interaction when selection changes frequently |
'explicit' | Requires Space or Enter to confirm selection, preventing accidental changes while navigating |
TIP: Dropdown patterns typically use 'follow' mode for single selection.
The ngListbox directive creates an accessible list of selectable options.
| 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 |
| Property | Type | Description |
|---|---|---|
values | V[] | Two-way bindable array of selected values |
| Property | Type | Description |
|---|---|---|
values | Signal<V[]> | Currently selected values as a signal |
| Method | Parameters | Description |
|---|---|---|
scrollActiveItemIntoView | options?: ScrollIntoViewOptions | Scrolls the active item into view |
gotoFirst | none | Navigates to the first item in the listbox |
The ngOption directive marks an item within a listbox.
| 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 |
| 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:
multiFor complete dropdown patterns with trigger, popup, and overlay positioning, see those pattern guides instead of using listbox alone.
<docs-pill-row> <docs-pill href="https://www.w3.org/WAI/ARIA/apg/patterns/listbox/" title="Listbox ARIA pattern"/> <docs-pill href="/api/aria/listbox/Listbox" title="Listbox API Reference"/> </docs-pill-row>