Autocomplete

Overview

The <mat-autocomplete> component provides a panel of suggested options that appears below a text input field. It enhances user experience by offering real-time suggestions based on user input.

Basic Usage

Template-driven
Reactive Forms

<mat-form-field>
  <mat-label>Choose an option</mat-label>
  <input type="text" matInput [matAutocomplete]="auto">
  <mat-autocomplete #auto="matAutocomplete">
    <mat-option *ngFor="let option of options" [value]="option">
      {{ option }}
    </mat-option>
  </mat-autocomplete>
</mat-form-field>

import { Component } from '@angular/core';
import { FormControl } from '@angular/forms';

@Component({
  selector: 'app-autocomplete-example',
  template: `
    <mat-form-field>
      <mat-label>Search</mat-label>
      <input type="text" matInput [formControl]="myControl" [matAutocomplete]="auto">
      <mat-autocomplete #auto="matAutocomplete">
        <mat-option *ngFor="let option of filteredOptions | async" [value]="option">
          {{ option }}
        </mat-option>
      </mat-autocomplete>
    </mat-form-field>
  `
})
export class AutocompleteExample {
  myControl = new FormControl('');
  options: string[] = ['One', 'Two', 'Three'];
  filteredOptions: Observable<string[]>;
  
  ngOnInit() {
    this.filteredOptions = this.myControl.valueChanges.pipe(
      startWith(''),
      map(value => this._filter(value))
    );
  }
  
  private _filter(value: string): string[] {
    const filterValue = value.toLowerCase();
    return this.options.filter(option => 
      option.toLowerCase().includes(filterValue)
    );
  }
}

API Reference

MatAutocomplete

Selector: mat-autocomplete Exported as: matAutocomplete

Inputs

displayWith

((value: any) => string) | null

default:"null"

Function that maps an option’s control value to its display value in the trigger.

autoActiveFirstOption

boolean

default:"false"

Whether the first option should be highlighted when the autocomplete panel is opened.

autoSelectActiveOption

boolean

default:"false"

Whether the active option should be selected as the user is navigating.

requireSelection

boolean

default:"false"

Whether the user is required to make a selection when interacting with the autocomplete. If enabled, the value will be reset if the user moves away without selecting.

panelWidth

string | number

Specify the width of the autocomplete panel. Can be any CSS sizing value, otherwise it will match the width of its host.

disableRipple

boolean

default:"false"

Whether ripples are disabled within the autocomplete panel.

class

string | string[]

CSS classes to apply to the autocomplete panel inside the overlay container.

hideSingleSelectionIndicator

boolean

Whether checkmark indicator for single-selection options is hidden.

aria-label

string

Aria label of the autocomplete.

aria-labelledby

string

Input that can be used to specify the aria-labelledby attribute.

Outputs

optionSelected

EventEmitter<MatAutocompleteSelectedEvent>

Event that is emitted whenever an option from the list is selected.

opened

EventEmitter<void>

Event that is emitted when the autocomplete panel is opened.

closed

EventEmitter<void>

Event that is emitted when the autocomplete panel is closed.

optionActivated

EventEmitter<MatAutocompleteActivatedEvent>

Emits whenever an option is activated using keyboard navigation.

Properties

string

Unique ID to be used by autocomplete trigger’s “aria-owns” property. Auto-generated with prefix mat-autocomplete-.

isOpen

boolean

Whether the autocomplete panel is open.

showPanel

boolean

Whether the autocomplete panel should be visible, depending on option length.

Events

MatAutocompleteSelectedEvent

source

MatAutocomplete

Reference to the autocomplete panel that emitted the event.

option

MatOption

Option that was selected.

Accessibility

The autocomplete trigger uses role="combobox" and manages aria-expanded, aria-owns, and aria-activedescendant attributes
Use aria-label or aria-labelledby to provide an accessible label for the autocomplete
The autocomplete panel uses role="listbox" and each option has role="option"
Keyboard navigation is fully supported (Arrow keys, Enter, Escape)
Screen readers announce the active option and selection changes

Advanced Usage

Display Value Formatting

export class AutocompleteDisplayExample {
  options: User[] = [
    {name: 'Mary', id: 1},
    {name: 'Shelley', id: 2}
  ];
  
  displayFn(user: User): string {
    return user && user.name ? user.name : '';
  }
}

<mat-autocomplete [displayWith]="displayFn">
  <mat-option *ngFor="let option of options" [value]="option">
    {{ option.name }}
  </mat-option>
</mat-autocomplete>

Auto-selection

Use autoActiveFirstOption to automatically highlight the first option when the panel opens:

<mat-autocomplete [autoActiveFirstOption]="true">
  <!-- options -->
</mat-autocomplete>

Require Selection

Ensure users select from the available options:

<mat-autocomplete [requireSelection]="true">
  <!-- options -->
</mat-autocomplete>

Form Controls

Navigation

Layout

Buttons & Indicators

Popups & Modals

Data Table

Overview

Basic Usage

API Reference

MatAutocomplete

Inputs

Outputs

Properties

Events

MatAutocompleteSelectedEvent

Accessibility

Advanced Usage

Display Value Formatting

Auto-selection

Require Selection

Build docs developers (and LLMs) love

Form Controls

Navigation

Layout

Buttons & Indicators

Popups & Modals

Data Table

​Overview

​Basic Usage

​API Reference

​MatAutocomplete

​Inputs

​Outputs

​Properties

​Events

​MatAutocompleteSelectedEvent

​Accessibility

​Advanced Usage

​Display Value Formatting

​Auto-selection

​Require Selection

Build docs developers (and LLMs) love

Overview

Basic Usage

API Reference

MatAutocomplete

Inputs

Outputs

Properties

Events

MatAutocompleteSelectedEvent

Accessibility

Advanced Usage

Display Value Formatting

Auto-selection

Require Selection