In-depth Guides
Angular Aria

Combobox

Overview

A directive that coordinates a trigger element (such as a text input, button, or div) with a popup, providing the primitive directive for autocomplete, select, and multiselect patterns.

Usage

Combobox is the primitive directive that coordinates an interactive trigger element (such as a text input, button, or div) with a popup. It provides the foundation for autocomplete, select, and multiselect patterns. Consider using combobox directly when:

  • Building custom autocomplete patterns - Creating specialized filtering or suggestion behavior
  • Creating custom selection components - Developing dropdowns with unique requirements
  • Coordinating input with popup - Pairing text input with listbox, tree, or dialog content
  • Implementing custom filtering - Filtering and orchestrating matching options in user space

Use documented patterns instead when:

  • Standard autocomplete with filtering is needed - See the Autocomplete pattern for ready-to-use examples
  • Single-selection dropdowns are needed - See the Select pattern for complete dropdown implementation
  • Multiple-selection dropdowns are needed - See the Multiselect pattern for multi-select with compact display

NOTE: The Autocomplete, Select, and Multiselect guides show documented patterns that combine this directive with Listbox for specific use cases.

Features

Angular's combobox provides a fully accessible input-popup coordination system with:

  • Trigger Element with Popup - Coordinates trigger element with popup content
  • Flexible Coordination - Integrates seamlessly with standard layouts (listbox, tree, grid, or dialog)
  • Keyboard Navigation - Arrow keys, Enter, Escape handling
  • Screen Reader Support - Built-in ARIA attributes including role="combobox" and aria-expanded
  • Popup Management - Automatic show/hide based on user interaction
  • Signal-Based Reactivity - Reactive state management using Angular signals

Examples

Autocomplete

An accessible input field that filters and suggests options as users type, helping them find and select values from a list.

Filtering is managed in user space by updating a signal that reactively filters the options list. Users navigate with arrow keys and select with Enter or click. This provides complete control and maximum flexibility for custom selection logic. See the Autocomplete guide for complete filtering patterns and examples.

Readonly mode

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

Triggering a dropdown without text input can be achieved using a button as the host trigger, or applying the native HTML readonly attribute to the input trigger. The popup opens on click or arrow keys.

This configuration provides the foundation for the Select and Multiselect patterns. See those guides for complete dropdown implementations with triggers and overlay positioning.

Datepicker grid

Combobox can coordinate with a two-dimensional grid to create accessible datepickers. Users navigate dates inside the calendar grid table using directional arrow keys and confirm selection with click, Enter, or Spacebar.

Dialog popup

Dialog popups combine the combobox trigger with standard dialog layouts and focus traps (such as CDK's cdkTrapFocus). Use dialog popups when the overlay requires modal behavior or backdrop interaction.

Testing

Angular Aria provides a ComboboxHarness for testing combobox components. Here is an example of how to use the harness in a component test:

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 {MyComboboxComponent} from './my-combobox'; // Your component

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

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

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

  it('should allow opening and closing the popup', async () => {
    const combobox = await loader.getHarness(ComboboxHarness);

    // Verify initial state
    expect(await combobox.isOpen()).toBe(false);

    // Open the popup
    await combobox.open();
    expect(await combobox.isOpen()).toBe(true);

    // Close the popup
    await combobox.close();
    expect(await combobox.isOpen()).toBe(false);
  });
});

APIs

Combobox Directive

Coordinates an interactive trigger element (such as a text input, button, or div) with a popup container.

Inputs / Model

Property Type Default Description
value ModelSignal<string> '' Two-way bindable text value of the combobox
expanded ModelSignal<boolean> false Two-way bindable open/closed expanded state of the popup
disabled boolean false Disables the combobox trigger element
softDisabled boolean true Disables interaction while keeping the element keyboard focusable
alwaysExpanded boolean false Forces the popup to always remain open
inlineSuggestion string | undefined - Sets an inline suggestion to be highlighted at the end of the input
tabIndex number | undefined - Tabindex of the combobox element (aliased to tabindex)

All keyboard events, focus coordination, and ARIA state properties (including role="combobox", aria-autocomplete, and aria-expanded) are handled automatically on the host element.

ComboboxPopup Directive

Marks an <ng-template> as the popup container for the combobox.

Inputs

Property Type Default Description
combobox Combobox (Required) Reference to the parent Combobox directive
popupType 'listbox' | 'tree' | 'grid' | 'dialog' 'listbox' Specifies the layout/role profile of the popup

ComboboxWidget Directive

Connects the popup contents (such as a listbox or grid) with the parent combobox trigger.

Inputs

Property Type Description
activeDescendant string | undefined The ID of the currently active option (bound to the active option ID in the widget)

Combobox is the primitive directive for these documented patterns:

  • Autocomplete - Filtering and suggestions pattern (coordinates input typing with options list)
  • Select - Single selection dropdown pattern (applied directly on non-editable button triggers)
  • Multiselect - Multiple selection pattern (applied on non-editable triggers with multi-enabled Listbox)

Combobox typically combines with:

  • Listbox - Most common popup content
  • Tree - Hierarchical popup content (see Tree guide for examples)