Angular Autocomplete

• See Demo or try in Stackblitz
• Example with images Stackblitz
• Example with Angular forms API Stackblitz

Table of contents

• Features
• Getting started
• Usage
• API
• Styles

Features

• Flexible autocomplete with client/server filtering.
• Variable properties and event bindings.
• Selection history.
• Custom item and 'not found' templates.
• Infinite scroll.
• Compatible with Angular forms API (Both Reactive and Template-driven forms).
• Keyboard navigation.
• Accessibility.

Getting started

Step 1: Install angular-ng-autocomplete:

NPM

npm i angular-ng-autocomplete

Step 2: Import the AutocompleteLibModule:

import {AutocompleteLibModule} from 'angular-ng-autocomplete';

@NgModule({
  declarations: [AppComponent],
  imports: [AutocompleteLibModule],
  bootstrap: [AppComponent]
})
export class AppModule {}

Usage sample

<div class="ng-autocomplete">
<ng-autocomplete 
  [data]="data"
  [searchKeyword]="keyword"
  (selected)='selectEvent($event)'
  (inputChanged)='onChangeSearch($event)'
  (inputFocused)='onFocused($event)'
  [itemTemplate]="itemTemplate"
  [notFoundTemplate]="notFoundTemplate">                                 
</ng-autocomplete>

<ng-template #itemTemplate let-item>
<a [innerHTML]="item.name"></a>
</ng-template>

<ng-template #notFoundTemplate let-notFound>
<div [innerHTML]="notFound"></div>
</ng-template>
</div>

class TestComponent {
  keyword = 'name';
  data = [
     {
       id: 1,
       name: 'Usa'
     },
     {
       id: 2,
       name: 'England'
     }
  ];


  selectEvent(item) {
    // do something with selected item
  }

  onChangeSearch(val: string) {
    // fetch remote data from here
    // And reassign the 'data' which is binded to 'data' property.
  }
  
  onFocused(e){
    // do something when input is focused
  }
}

API

Inputs

Input	Type	Default	Required	Description
[data]	Array<any>	null	yes	Data of items list. It can be array of strings or array of objects.
searchKeyword	string	-	yes	Variable name to filter data with.
placeHolder	string	-	no	HTML <input> placeholder text.
heading	string	-	no	Heading text of items list. If it is null then heading is hidden.
initialValue	any	_	no	initial/default selected value.
historyIdentifier	string	_	no	History identifier of history list. When valid history identifier is given, then component stores selected item to local storage of user's browser. If it is null then history is hidden. History list is visible if at least one history item is stored. History identifier must be unique.
historyHeading	string	Recently selected	no	Heading text of history list. If it is null then history heading is hidden.
historyListMaxNumber	number	15	no	Maximum number of items in the history list.
name	string	_	yes (If NgModel is used within a form tag)	Tracks the name bound to the NgModel directive. For more details click here
[(ngModel)]	any	_	no	Tracks the value bound to this directive. Used with Template-driven forms. For more details click here
[formControl] / formControlName	string	_	no	Tracks the FormControl instance bound to the directive. Used with Reactive forms. For more details click here and here
notFoundText	string	Not found	no	Set custom text when filter returns empty result.
isLoading	boolean	false	no	Set the loading state when data is being loaded.
minQueryLength	number	1	no	The minimum number of characters the user must type before a search is performed.
debounceTime	number	400	no	Delay time while typing.
disabled	boolean	false	no	input disable/enable.
autoSelectFirst	boolean	false	no	Automatically select the first matched option on the list

Outputs

Output	Description
(selected)	Event is emitted when an item from the list is selected.
(inputChanged)	Event is emitted when an input is changed.
(inputFocused)	Event is emitted when an input is focused.
(inputCleared)	Event is emitted when an input is cleared.
(opened)	Event is emitted when the autocomplete panel is opened.
(closed)	Event is emitted when the autocomplete panel is closed.
(scrolledToEnd)	Event is emitted when scrolled to the end of items. Can be used for loading more items in chunks.

Methods (controls)

Name	Description
open	Opens the autocomplete panel
close	Closes the autocomplete panel
focus	Focuses the autocomplete input element
clear	Clears the autocomplete input element

To access the control methods of the component you should use @ViewChild decorator. See the example below:

<ng-autocomplete #auto></ng-autocomplete>

class TestComponent {
  @ViewChild('auto') auto;

  openPanel(e): void {
    e.stopPropagation();
    this.auto.open();
  }
  
  closePanel(e): void {
    e.stopPropagation();
    this.auto.close();
    }
    
  focus(e): void {
    e.stopPropagation();
    this.auto.focus();
  }  
}

Styles

If you are not happy with default styles you can easily override them:

<div class="ng-autocomplete">
<ng-autocomplete></ng-autocomplete>
</div>

.ng-autocomplete {
    width: 400px;
}

Support Angular autocomplete!

If you do love angular-ng-autocomplete I would appreciate a donation :)

Author

• Giorgi Merabishvili

License

MIT