In-depth Guides
Angular Aria

Select

Overview

A pattern that combines a combobox with a listbox to create single-selection dropdowns with keyboard navigation and screen reader support.

Usage

The select pattern works best when users need to choose a single value from a familiar set of options.

Consider using this pattern when:

  • The option list is fixed (fewer than 20 items) - Users can scan and choose without filtering
  • Options are familiar - Users recognize the choices without needing to search
  • Forms need standard fields - Country, state, category, or status selection
  • Settings and configuration - Dropdown menus for preferences or options
  • Clear option labels - Each choice has a distinct, scannable name

Avoid this pattern when:

  • The list has more than 20 items - Use the Autocomplete pattern for better filtering
  • Users need to search options - Autocomplete provides text input and filtering
  • Multiple selection is needed - Use the Multiselect pattern instead
  • Very few options exist (2-3) - Radio buttons provide better visibility of all choices

Features

The select pattern combines Combobox and Listbox directives to provide a fully accessible dropdown with:

  • Keyboard Navigation - Navigate options with arrow keys, select with Enter, close with Escape
  • Screen Reader Support - Built-in ARIA attributes for assistive technologies
  • Custom Display - Show selected values with icons, formatting, or rich content
  • Signal-Based Reactivity - Reactive state management using Angular signals
  • Smart Positioning - CDK Overlay handles viewport edges and scrolling
  • Bidirectional Text Support - Automatically handles right-to-left (RTL) languages

Examples

Basic select

Users need a standard dropdown to choose from a list of values. A combobox paired with a listbox provides the familiar select experience with full accessibility support.

Text input is prevented by applying the ngCombobox directive directly onto a non-interactive host element (such as a div or a button) instead of an <input>. Users interact with the dropdown using arrow keys and Enter, just like a native select element.

Select with custom display

Options often need visual indicators like icons or badges to help users identify choices quickly. Custom templates within options allow rich formatting while maintaining accessibility.

Each option displays an icon alongside the label. The selected value updates to show the chosen option's icon and text, providing clear visual feedback.

Disabled select

Selects can be disabled to prevent user interaction when certain form conditions aren't met. The disabled state provides visual feedback and prevents keyboard interaction.

When disabled, the select shows a disabled visual state and blocks all user interaction. Screen readers announce the disabled state to assistive technology users.

Testing

The select pattern can be tested using a combination of ComboboxHarness and ListboxHarness from @angular/aria/combobox/testing and @angular/aria/listbox/testing. Here is an example of how to use the harnesses to test a select component:

import {ComponentFixture, TestBed} from '@angular/core/testing';
import {HarnessLoader} from '@angular/cdk/testing';
import {TestbedHarnessEnvironment} from '@angular/cdk/testing/testbed';
import {ComboboxHarness} from '@angular/aria/combobox/testing';
import {ListboxHarness} from '@angular/aria/listbox/testing';
import {MySelectComponent} from './my-select'; // Your component

describe('MySelectComponent', () => {
  let fixture: ComponentFixture<MySelectComponent>;
  let loader: HarnessLoader;

  beforeEach(async () => {
    TestBed.configureTestingModule({
      imports: [MySelectComponent],
    });

    fixture = TestBed.createComponent(MySelectComponent);
    await fixture.whenStable();
    loader = TestbedHarnessEnvironment.loader(fixture);
  });

  it('should allow selecting an option', async () => {
    // Load the combobox harness (which acts as the select trigger)
    const select = await loader.getHarness(ComboboxHarness);

    // Verify it is closed initially
    expect(await select.isOpen()).toBe(false);

    // Open the dropdown
    await select.open();
    expect(await select.isOpen()).toBe(true);

    // Get the listbox harness from the popup
    const listbox = await select.getPopupWidget(ListboxHarness);
    const options = await listbox.getOptions();
    expect(options.length).toBe(3);

    // Click the second option
    await options[1].click();

    // Verify the dropdown closed and the value updated
    expect(await select.isOpen()).toBe(false);
    expect(await (await select.host()).text()).toContain('Option 2');
  });
});

APIs

The select pattern uses the following directives from Angular's Aria library. See the full API documentation in the linked guides.

Combobox Directives

The select pattern applies ngCombobox directly onto a non-interactive host element (such as a div or a button) to prevent text input while preserving keyboard navigation.

Inputs

Property Type Default Description
disabled boolean false Disables the entire select
expanded ModelSignal<boolean> false Expanded state of select

See the Combobox API documentation for complete details on all available inputs and signals.

The structural ngComboboxPopup directive marks the overlay template and requires a reference to the parent combobox:

Property Type Description
combobox Combobox Required reference to the parent Combobox

ComboboxWidget Directive

The ngComboboxWidget directive bridges the listbox with the combobox trigger to support active-descendant focus tracking.

Property Type Description
activeDescendant string | undefined The ID of the currently active option (bound to listbox.activeDescendant()) to update the aria-activedescendant attribute on the trigger

Listbox Directives

The select pattern uses ngListbox for the dropdown list and ngOption for each selectable item.

Inputs

Property Type Default Description
selectionMode 'follow' | 'explicit' 'explicit' Set to 'explicit' so options are toggled explicitly via click/Enter instead of following active focus
focusMode 'roving' | 'activedescendant' 'roving' The focus strategy used by the listbox. Set to 'activedescendant' so browser focus remains on the combobox trigger.
tabIndex number 0 The tabindex of the listbox. Set to -1 to prevent keyboard focus from entering the popup container in active-descendant mode.

Model

Property Type Description
value ModelSignal<any[]> Two-way bindable array of selected values (contains single value for select)

Positioning

The select pattern integrates with CDK Overlay for smart positioning. Use cdkConnectedOverlay to handle viewport edges and scrolling automatically.