ngx-mat-autocomplete-control

A powerful, ready-to-use Angular Material Autocomplete component that works seamlessly with Reactive Forms. Drop it into any Angular project and get a fully featured searchable dropdown with highlighting, validation, and keyboard support — in minutes, not hours.

Features

• Reactive Forms support out of the box (FormControl / FormGroup)
• Search-as-you-type with real-time filtering
• Highlight matching text in dropdown options (customizable color)
• Built-in validation — required field + invalid selection errors
• Keyboard navigation — full arrow-key, Enter, and Tab support
• Configurable appearance — supports all Material form-field appearances (outline, fill)
• Lightweight — thin wrapper around Angular Material with zero extra dependencies
• Always up to date — supports Angular 21 and Angular Material 21

Demo

Try the live demo on StackBlitz

Installation

npm install ngx-mat-autocomplete-control

Peer Dependencies

Make sure you have these installed in your project:

| Package | Version | | -------------------- | --------- | | @angular/core | ^21.0.0 | | @angular/common | ^21.0.0 | | @angular/forms | ^21.0.0 | | @angular/material | ^21.0.0 | | @angular/cdk | ^21.0.0 |

For older Angular versions, use [email protected].

Angular Material Theme

This package requires an Angular Material theme. Add one to your angular.json styles array:

"styles": [
  "@angular/material/prebuilt-themes/indigo-pink.css"
]

Or import it in your global styles.scss:

@import '@angular/material/prebuilt-themes/indigo-pink.css';

Other available prebuilt themes: azure-blue, magenta-violet, cyan-orange, rose-red.

Quick Start

1. Import the module

import { NgxMatAutocompleteControlModule } from 'ngx-mat-autocomplete-control';

@NgModule({
  imports: [
    NgxMatAutocompleteControlModule
  ]
})
export class AppModule {}

2. Add the component to your template

<ngx-mat-autocomplete-control
  [control]="'userId' | autocompleteControl: userForm:'':-1"
  [options]="userList"
  [required]="true"
  [refId]="'userId'"
  [refName]="'userName'"
  [label]="'Select User'"
  [appearance]="'outline'"
  [highlightColor]="'red'"
  (selectionChange)="onUserSelected($event)">
</ngx-mat-autocomplete-control>

3. Set up the component class

import { Component, OnInit } from '@angular/core';
import { FormBuilder, FormGroup, Validators } from '@angular/forms';

@Component({
  selector: 'app-user-picker',
  templateUrl: './user-picker.component.html'
})
export class UserPickerComponent implements OnInit {
  userForm!: FormGroup;

  userList = [
    { userId: 1, userName: 'Sriram M P' },
    { userId: 2, userName: 'Balamurugan' },
    { userId: 3, userName: 'Subashini' },
    { userId: 4, userName: 'Narmatha' }
  ];

  constructor(private fb: FormBuilder) {}

  ngOnInit(): void {
    this.userForm = this.fb.group({
      userId: ['', Validators.required]
    });
  }

  onUserSelected(event: { value: any; data: any; control: any }): void {
    console.log('Selected ID:', event.value);
    console.log('Selected object:', event.data);
  }
}

API Reference

Inputs

| Property | Type | Default | Description | | ------------------ | ------------------- | ----------- | ----------------------------------------------------------------------- | | control | AbstractControl | — | The FormControl to bind the selected value to | | options | any[] | [] | Array of objects to display as dropdown options | | refId | string | '' | Property name used as the value (stored in the form control) | | refName | string | '' | Property name used as the display text and search term | | label | string | '' | Placeholder / label for the form field | | required | boolean | false | Whether the field is required | | highlightColor | string | 'black' | Color used to highlight matching text in the dropdown | | appearance | string | 'outline' | Material form-field appearance: 'outline' or 'fill' | | checkValid | boolean | true | Whether to validate that the typed text matches a valid option | | showDefaultSelect| boolean | false | When true, skips auto-selecting the first matching option on blur | | disabled | boolean | false | Disables the input |

Outputs

| Event | Payload | Description | | ----------------- | -------------------------------------------------------------- | ------------------------------------------ | | selectionChange | { value: any, data: any, control: UntypedFormControl } | Fires when the user picks an option |

• value — the refId field value of the selected option
• data — the full selected option object from options
• control — the bound FormControl

Pipe: autocompleteControl

A helper pipe to extract the correct FormControl from nested form structures.

'controlName' | autocompleteControl: formGroup : subFormName : formArrayIndex

| Param | Description | | ---------------- | --------------------------------------------------- | | formGroup | The parent FormGroup | | subFormName | Nested FormGroup or FormArray name ('' if none) | | formArrayIndex | Index inside a FormArray (-1 if not applicable) |

Examples

Basic usage (flat form)

<ngx-mat-autocomplete-control
  [control]="'cityId' | autocompleteControl: myForm:'':-1"
  [options]="cities"
  [refId]="'id'"
  [refName]="'name'"
  [label]="'City'">
</ngx-mat-autocomplete-control>

Inside a FormArray

<div *ngFor="let item of items.controls; let i = index">
  <ngx-mat-autocomplete-control
    [control]="'productId' | autocompleteControl: myForm:'items':i"
    [options]="products"
    [refId]="'id'"
    [refName]="'productName'"
    [label]="'Product'">
  </ngx-mat-autocomplete-control>
</div>

With custom highlight color

<ngx-mat-autocomplete-control
  [control]="'countryId' | autocompleteControl: myForm:'':-1"
  [options]="countries"
  [refId]="'code'"
  [refName]="'countryName'"
  [label]="'Country'"
  [highlightColor]="'#1976d2'"
  [appearance]="'fill'">
</ngx-mat-autocomplete-control>

Version Compatibility

| Library Version | Angular Version | | --------------- | --------------- | | 4.x | 21 | | 2.x | 13 – 19 |

Contributing

Contributions, issues, and feature requests are welcome!

• Open an Issue
• View Existing Issues

Support

If you found this package useful, give it a star on GitHub and share it with others.

You can also support via UPI: sribala333@ybl

License

ISC © Sriram M P