Angular AutoComplete is an input component that provides real-time suggestions when being typed.
Setup
Refer to PrimeNG setup documentation for download and installation steps for your environment.
Import
import {AutoCompleteModule} from 'primeng/autocomplete';
Getting Started
AutoComplete uses ngModel for two-way binding, requires a list of suggestions and a completeMethod to query for the results. The completeMethod gets the query text as event.query property and should update the suggestions with the search results.
<p-autoComplete [(ngModel)]="text" [suggestions]="results" (completeMethod)="search($event)"></p-autoComplete>
export class AutoCompleteDemo {
text: string;
results: string[];
search(event) {
this.mylookupservice.getResults(event.query).then(data => {
this.results = data;
});
}
}
Change Detection of Suggestions
AutoComplete uses setter based checking to realize if the suggestions has changed to update the UI. In order this to work, your changes such as adding or removing a record should always create a new array reference instead of manipulating an existing array as Angular does not trigger setters if the reference does not change.
Note that if no suggestions are available after searching, provide an empty array instead of a null value.
Model Driven Forms
AutoComplete can be used in a model driven form as well.
<p-autoComplete formControlName="city" [suggestions]="results" (completeMethod)="search($event)"></p-autoComplete>
Dropdown
Enabling dropdown property displays a button next to the input field where click behavior of the button is defined using dropdownMode property that takes "blank" or "current" as possible values. "blank" is the default mode to send a query with an empty string whereas "current" setting sends a query with the current value of the input.
<p-autoComplete [(ngModel)]="text" [suggestions]="results" (completeMethod)="search($event)"
[dropdown]="true"></p-autoComplete>
export class AutoCompleteDemo {
text: string;
results: string[];
search(event) {
this.mylookupservice.getResults(event.query).then(data => {
this.results = data;
});
}
handleDropdown(event) {
//event.query = current value in input field
}
}
Multiple Selection
Multiple mode is enabled using multiple property to select more than one value from the autocomplete. In this case, value reference should be an array.
<p-autoComplete [(ngModel)]="texts" [suggestions]="results" (completeMethod)="search($event)" [multiple]="true"></p-autoComplete>
export class AutoCompleteDemo {
texts: string[];
results: string[];
search(event) {
this.mylookupservice.getResults(event.query).then(data => {
this.results = data;
});
}
}
Objects
AutoComplete can also work with objects using the field property that defines the label to display as a suggestion. The value passed to the model would still be the object instance of a suggestion. Here is an example with a Country object that has name and code fields such as {name:"United States",code:"USA"}.
<p-autoComplete [(ngModel)]="val" [suggestions]="results" (completeMethod)="search($event)" field="name"></p-autoComplete>
export class AutoCompleteDemo {
val: country;
results: country[];
search(event) {
this.countrylookupservice.getResults(event.query).then(data => {
this.results = data;
});
}
}
Force Selection
ForceSelection mode validates the manual input to check whether it also exists in the suggestions list, if not the input value is cleared to make sure the value passed to the model is always one of the suggestions.
<p-autoComplete [(ngModel)]="val" [suggestions]="results" (completeMethod)="search($event)" [forceSelection]="true"></p-autoComplete>
Templating
Item ng-template allows displaying custom content inside the suggestions panel. The local ng-template variable passed to the ng-template is an object in the suggestions array.
<p-autoComplete [(ngModel)]="brand" [suggestions]="filteredBrands" (completeMethod)="filterBrands($event)">
<ng-template let-brand pTemplate="item">
<img src="assets/showcase/images/demo/car/{{brand}}.png" style="width:32px;display:inline-block;margin:5px 0 2px 5px"/>
<div style="font-size:18px;float:right;margin:10px 10px 0 0">{{brand}}</div>
</ng-template>
</p-autoComplete>
In multiple mode, selected item can be customized using selectedItem ng-template. Note that this template is not supported in single mode. In addition when grouping is enabled, group template is available to customize the option groups. All templates get the option instance as the default local template variable.
<p-autoComplete [(ngModel)]="texts" [suggestions]="results" (completeMethod)="search($event)" [multiple]="true">
<ng-template let-value pTemplate="selectedItem">
<span style="font-size:18px">>{{value}}<</span>
</ng-template>
</p-autoComplete>
Animation Configuration
Transition of the open and hide animations can be customized using the showTransitionOptions and hideTransitionOptions properties, example below disables the animations altogether.
<p-autoComplete [showTransitionOptions]="'0ms'" [hideTransitionOptions]="'0ms'" [(ngModel)]="texts" [suggestions]="results" (completeMethod)="search($event)"></p-autoComplete>
Theming
AutoComplete supports various themes featuring Material, Bootstrap, Fluent as well as your own custom themes via the Designer tool.
Resources
Visit the PrimeNG AutoComplete showcase for demos and documentation.