@angular/aria/combobox

Combobox

Class

The container element that wraps a combobox input and popup, and orchestrates its behavior.

API

    
      class Combobox<V> {}

textDirection

Signal<Direction>

A signal wrapper for directionality.

element

HTMLElement

A reference to the combobox element.

filterMode

InputSignal<"manual" | "auto-select" | "highlight">

The filter mode for the combobox.

manual: The consumer is responsible for filtering the options.
auto-select: The combobox automatically selects the first matching option.
highlight: The combobox highlights matching text in the options without changing selection.

disabled

InputSignalWithTransform<boolean, unknown>

Whether the combobox is disabled.

readonly

InputSignalWithTransform<boolean, unknown>

Whether the combobox is read-only.

firstMatch

InputSignal<V | undefined>

The value of the first matching item in the popup.

expanded

Signal<any>

Whether the combobox is expanded.

alwaysExpanded

InputSignalWithTransform<boolean, unknown>

Whether the combobox popup should always be expanded, regardless of user interaction.

inputElement

Signal<any>

Input element connected to the combobox, if any.

open

void

Opens the combobox to the selected item.

@returnsvoid

close

void

Closes the combobox.

@returnsvoid

Description

The container element that wraps a combobox input and popup, and orchestrates its behavior.

The ngCombobox directive is the main entry point for creating a combobox and customizing its behavior. It coordinates the interactions between the ngComboboxInput and the popup, which is defined by a ng-template with the ngComboboxPopupContainer directive. If using the CdkOverlay, the cdkConnectedOverlay directive takes the place of ngComboboxPopupContainer.

<div ngCombobox filterMode="highlight">
  <input
    ngComboboxInput
    placeholder="Search for a state..."
    [(value)]="searchString"
  />

  <ng-template ngComboboxPopupContainer>
    <div ngListbox [(value)]="selectedValue">
      @for (option of filteredOptions(); track option) {
        <div ngOption [value]="option" [label]="option">
          <span>{{option}}</span>
        </div>
      }
    </div>
  </ng-template>
</div>