W3cubDocs

/Angular

Combobox

Overview

A directive that coordinates a text input with a popup, providing the primitive directive for autocomplete, select, and multiselect patterns.

Usage

Combobox is the primitive directive that coordinates a text input 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 specific filter modes - Using manual, auto-select, or highlight behaviors

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:

  • Text Input with Popup - Coordinates input field with popup content
  • Three Filter Modes - Manual, auto-select, or highlight behaviors
  • 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.

The filterMode="manual" setting gives complete control over filtering and selection. The input updates a signal that filters the options list. Users navigate with arrow keys and select with Enter or click. This mode provides the most flexibility for custom filtering 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.

The readonly attribute prevents typing in the input field. The popup opens on click or arrow keys. Users navigate options with keyboard and select with Enter or click.

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

Dialog popup

Popups sometimes need modal behavior with a backdrop and focus trap. The combobox dialog directive provides this pattern for specialized use cases.

The ngComboboxDialog directive creates a modal popup using the native dialog element. This provides backdrop behavior and focus trapping. Use dialog popups when the selection interface requires modal interaction or when the popup content is complex enough to warrant full-screen focus.

APIs

Combobox Directive

The ngCombobox directive coordinates a text input with a popup.

Inputs

Property Type Default Description
filterMode 'manual' | 'auto-select' | 'highlight' 'manual' Controls selection behavior
disabled boolean false Disables the combobox
readonly boolean false Makes combobox readonly (for Select/Multiselect)
firstMatch V - Value of first matching item for auto-select
alwaysExpanded boolean false Keeps popup always open

Filter Modes:

  • 'manual' - User controls filtering and selection explicitly. The popup shows options based on your filtering logic. Users select with Enter or click. This mode provides the most flexibility.
  • 'auto-select' - Input value automatically updates to the first matching option as users type. Requires the firstMatch input for coordination. See the Autocomplete guide for examples.
  • 'highlight' - Highlights matching text without changing the input value. Users navigate with arrow keys and select with Enter.

Signals

Property Type Description
expanded Signal<boolean> Whether popup is currently open

Methods

Method Parameters Description
open none Opens the combobox
close none Closes the combobox
expand none Expands the combobox
collapse none Collapses the combobox

ComboboxInput Directive

The ngComboboxInput directive connects an input element to the combobox.

Model

Property Type Description
value string Two-way bindable value using [(value)]

The input element receives keyboard handling and ARIA attributes automatically.

ComboboxPopup Directive

The ngComboboxPopup directive (host directive) manages popup visibility and coordination. Typically used with ngComboboxPopupContainer in an ng-template or with CDK Overlay.

ComboboxPopupContainer Directive

The ngComboboxPopupContainer directive marks an ng-template as the popup content.

<ng-template ngComboboxPopupContainer>
  <div ngListbox>...</div>
</ng-template>

Used with Popover API or CDK Overlay for positioning.

ComboboxDialog Directive

The ngComboboxDialog directive creates a modal combobox popup.

<dialog ngComboboxDialog>
  <div ngListbox>...</div>
</dialog>

Use for modal popup behavior with backdrop and focus trap.

Combobox is the primitive directive for these documented patterns:

  • Autocomplete - Filtering and suggestions pattern (uses Combobox with filter modes)
  • Select - Single selection dropdown pattern (uses Combobox with readonly)
  • Multiselect - Multiple selection pattern (uses Combobox with readonly + multi-enabled Listbox)

Combobox typically combines with:

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

Super-powered by Google ©2010–2025.
Code licensed under an MIT-style License. Documentation licensed under CC BY 4.0.
https://angular.dev/guide/aria/combobox