🚀 Mastering MatAutocomplete in Angular Material: A Practical Guide

Autocomplete dramatically improves user experience by making form interactions faster and more intuitive. If you’re working with Angular, MatAutocomplete from Angular Material is a sleek and flexible solution—but like many tools, it can trip you up if you’re not careful.

In this article, I’ll walk you through setting up MatAutocomplete properly, and more importantly, break down the most common pitfalls developers face—and how to fix them quickly.

---

⚙️ Step-by-Step: Setting Up MatAutocomplete

Before we dig into bugs and fixes, let’s start with the basic setup.

1. Install Angular Material

ng add @angular/material

2. Import Required Modules

Add these modules in your AppModule:

import { MatAutocompleteModule } from '@angular/material/autocomplete';
import { MatInputModule } from '@angular/material/input';
import { ReactiveFormsModule } from '@angular/forms';

@NgModule({
  imports: [
    MatAutocompleteModule,
    MatInputModule,
    ReactiveFormsModule
  ]
})
export class AppModule {}

3. Basic Implementation

<mat-form-field appearance="fill">
  <input
    type="text"
    matInput
    placeholder="Search"
    [formControl]="myControl"
    [matAutocomplete]="auto">
  <mat-autocomplete #auto="matAutocomplete">
    <mat-option *ngFor="let option of filteredOptions" [value]="option">
      {{ option }}
    </mat-option>
  </mat-autocomplete>
</mat-form-field>

myControl = new FormControl();
options: string[] = ['One', 'Two', 'Three'];
filteredOptions: 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));
}

---

🐞 Common MatAutocomplete Issues and How to Fix Them

🔹 1. Dropdown Not Appearing

Symptoms: You type into the input, but nothing shows.

Possible Causes:

• [matAutocomplete] not correctly bound
• filteredOptions not updating
• No matching options

Quick Fix:

• Make sure your input has [matAutocomplete]="auto"
• Check if filteredOptions is defined and reactive (e.g., using valueChanges)
• Ensure <mat-option> elements are inside <mat-autocomplete>

---

🔹 2. Showing [object Object] Instead of Text

Symptoms: You select an item and the input displays [object Object].

Root Cause: You’re binding objects instead of strings.

Fix: Use displayWith to tell Angular how to render the value.

<mat-autocomplete #auto="matAutocomplete" [displayWith]="displayFn">
  <mat-option *ngFor="let user of filteredUsers" [value]="user">
    {{ user.name }}
  </mat-option>
</mat-autocomplete>

displayFn(user: any): string {
  return user?.name || '';
}

---

🔹 3. Arrow Keys Not Navigating Options

Fix Checklist:

• Confirm you’re using matInput
• Input must be focusable
• FormControl is correctly bound

This generally works out of the box if your setup is right.

---

🔹 4. Autocomplete Closes Immediately

Why It Happens: A blur or click event (like a wrapper div with a click handler) is stealing focus.

Fix: Avoid wrapping your form field in clickable containers or interfering with focus events.

---

🔹 5. Case-Sensitive Filtering

Problem: Users expect to type lowercase and still find uppercase options.

Fix: Normalize both the input and the options.

private _filter(value: string): string[] {
  const filterValue = value.toLowerCase();
  return this.options.filter(option =>
    option.toLowerCase().includes(filterValue)
  );
}

---

🔹 6. Initial Value Doesn’t Display

Problem: You set a value, but the input appears blank.

Common Cause: When using objects, displayWith is mandatory.

myControl.setValue({ id: 1, name: 'John' });

displayFn(user: any): string {
  return user?.name || '';
}

---

🔹 7. Async Data from an API

Problem: Input changes, but autocomplete doesn’t update.

Fix: Use switchMap for API calls to avoid race conditions.

this.filteredOptions = this.myControl.valueChanges.pipe(
  debounceTime(300),
  distinctUntilChanged(),
  switchMap(value => this.fetchOptions(value))
);

---

✅ Pro Tips for a Smooth Autocomplete

• Use debounceTime() and distinctUntilChanged() to limit unnecessary API calls.
• For large datasets, always lazy-load options.
• Use (onSelectionChange) for custom selection logic:

<mat-option (onSelectionChange)="onSelect($event, option)">

---

🏁 Final Thoughts

MatAutocomplete is an excellent tool for modern Angular forms—but small misconfigurations can lead to frustrating issues. Most bugs come down to misunderstanding reactive forms, missing displayWith, or not properly handling objects.

Once you’ve nailed the setup, implementing autocompletes becomes a fast, reliable part of your UI toolbox.

Have you hit other roadblocks with MatAutocomplete? Share your experience and let’s keep building smarter forms—autocomplete style. 🔍