The @angular/cdk/listbox module provides directives to help create custom listbox interactions based on the WAI ARIA listbox pattern.

By using @angular/cdk/listbox you get all the expected behaviors for an accessible experience, including bidi layout support, keyboard interaction, and focus management. All directives apply their associated ARIA roles to their host element.

Supported ARIA Roles

The directives in @angular/cdk/listbox set the appropriate roles on their host element.

Directive	ARIA Role
cdkOption	option
cdkListbox	listbox

CSS Styles and Classes

The @angular/cdk/listbox is designed to be highly customizable to your needs. It therefore does not make any assumptions about how elements should be styled. You are expected to apply any required CSS styles, but the directives do apply CSS classes to make it easier for you to add custom styles. The available CSS classes are listed below, by directive.

Directive	CSS Class	Applied...
cdkOption	.cdk-option	Always
cdkOption	.cdk-option-active	If the option is active
cdkListbox	.cdk-listbox	Always

In addition to CSS classes, these directives add aria attributes that can be targeted in CSS.

Directive	Attribute Selector	Applied...
cdkOption	[aria-disabled="true"]	If the option is disabled
cdkOption	[aria-disabled="false"]	If the option is not disabled
cdkOption	[aria-selected="true"]	If the option is selected
cdkOption	[aria-selected="false"]	If the option is not selected
cdkListbox	[aria-disabled="true"]	If the listbox is disabled
cdkListbox	[aria-disabled="false"]	If the listbox is not disabled
cdkListbox	[aria-multiselectable="true"]	If the listbox is multiple selection
cdkListbox	[aria-multiselectable="false"]	If the listbox is single selection
cdkListbox	[aria-orientation="horizontal"]	If the listbox is oriented horizontally
cdkListbox	[aria-orientation="vertical"]	If the listbox is oriented vertically

Getting started

Import the CdkListboxModule into the NgModule in which you want to create a listbox. You can then apply listbox directives to build your custom listbox. A typical listbox consists of the following directives:

• cdkListbox - Added to the container element containing the options to be selected
• cdkOption - Added to each selectable option in the listbox

Option values

Each option in a listbox is bound to the value it represents when selected, e.g. <li cdkOption="red">Red</li>. Within a single listbox, each option must have a unique value. If an option is not explicitly given a value, its value is considered to be '' (empty string), e.g. <li cdkOption>No color preference</li>.

Single vs multiple selection

Listboxes only support a single selected option at a time by default, but adding cdkListboxMultiple will enable selecting more than one option.

Listbox value

The listbox's value is an array containing the values of the selected option(s). This is true even for the single selection listbox, whose value is an array containing a single element. The listbox's value can be bound using [cdkListboxValue] and (cdkListboxValueChange).

Internally the listbox compares the listbox value against the individual option values using Object.is to determine which options should appear selected. If your option values are complex objects, you should provide a custom comparison function instead. This can be set via the cdkListboxCompareWith input on the listbox.

Angular Forms support

The CDK Listbox supports both template driven forms and reactive forms.

Forms validation

The CDK listbox integrates with Angular's form validation API and has the following built-in validation errors:

• cdkListboxUnexpectedOptionValues - Raised when the bound value contains values that do not appear as option value in the listbox. The validation error contains a values property that lists the invalid values
• cdkListboxUnexpectedMultipleValues - Raised when a single-selection listbox is bound to a value containing multiple selected options.

Disabling options

You can disable options for selection by setting cdkOptionDisabled. In addition, the entire listbox control can be disabled by setting cdkListboxDisabled on the listbox element.

Accessibility

The directives defined in @angular/cdk/listbox follow accessibility best practices as defined in the ARIA spec. Keyboard interaction is supported as defined in the ARIA listbox keyboard interaction spec without the optional selection follows focus logic (TODO: should we make this an option?).

Listbox label

Always give the listbox a meaningful label for screen readers. If your listbox has a visual label, you can associate it with the listbox using aria-labelledby, otherwise you should provide a screen-reader-only label with aria-label.

Roving tabindex vs active descendant

By default, the CDK listbox uses the roving tabindex strategy to manage focus. If you prefer to use the aria-activedescendant strategy instead, set useActiveDescendant=true on the listbox.

Orientation

Listboxes assume a vertical orientation by default, but can be customized by setting the cdkListboxOrientation input. Note that this only affects the keyboard navigation. You will still need to adjust your CSS styles to change the visual appearance.

Option typeahead

The CDK listbox supports typeahead based on the option text. If the typeahead text for your options needs to be different than the display text (e.g. to exclude emoji), this can be accomplished by setting the cdkOptionTypeaheadLabel on the option.

Keyboard navigation options

When using keyboard navigation to navigate through the options, the navigation wraps when attempting to navigate past the start or end of the options. To change this, set cdkListboxNavigationWrapDisabled on the listbox.

Keyboard navigation skips disabled options by default. To change this set cdkListboxNavigatesDisabledOptions on the listbox.