AutoComplete is an input component that provides real-time suggestions when being typed.
import { AutoCompleteModule } from 'primeng/autocomplete';
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)]="value" [suggestions]="items" (completeMethod)="search($event)" />
AutoComplete can also be used with reactive forms. In this case, the formControlName property is used to bind the component to a form control.
<form [formGroup]="formGroup">
<p-autocomplete formControlName="selectedCountry" [suggestions]="filteredCountries" (completeMethod)="filterCountry($event)" field="name" />
</form>
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)]="value" [dropdown]="true" [suggestions]="items" (completeMethod)="search($event)" />
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)]="selectedCountry" [suggestions]="filteredCountries" (completeMethod)="filterCountry($event)" optionLabel="name" />
AutoComplete offers multiple templates for customization through templating.
<p-autocomplete [(ngModel)]="selectedCountryAdvanced" [suggestions]="filteredCountries" (completeMethod)="filterCountry($event)" optionLabel="name">
<ng-template let-country #item>
<div class="flex items-center gap-2">
<img src="https://primefaces.org/cdn/primeng/images/demo/flag/flag_placeholder.png" [class]="'flag flag-' + country.code.toLowerCase()" style="width: 18px" />
<div>{{ country.name }}</div>
</div>
</ng-template>
<ng-template #header>
<div class="font-medium px-3 py-2">Available Countries</div>
</ng-template>
<ng-template #footer>
<div class="px-3 py-3">
<p-button label="Add New" fluid severity="secondary" text size="small" icon="pi pi-plus" />
</div>
</ng-template>
</p-autocomplete>
Option grouping is enabled when group property is set to true. group template is available to customize the option groups. All templates get the option instance as the default local template variable.
<p-autocomplete [(ngModel)]="selectedCity" [group]="true" [suggestions]="filteredGroups" (completeMethod)="filterGroupedCity($event)" placeholder="Hint: type 'a'">
<ng-template let-group #group>
<div class="flex items-center">
<img src="https://primefaces.org/cdn/primeng/images/demo/flag/flag_placeholder.png" [class]="'mr-2 flag flag-' + group.value" style="width: 20px" />
<span>{{ group.label }}</span>
</div>
</ng-template>
</p-autocomplete>
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)]="selectedCountry" [forceSelection]="true" [suggestions]="filteredCountries" (completeMethod)="filterCountry($event)" optionLabel="name" />
Virtual scrolling is an efficient way of rendering the options by displaying a small subset of data in the viewport at any time. When dealing with huge number of options, it is suggested to enable virtual scrolling to avoid performance issues. Usage is simple as setting virtualScroll property to true and defining virtualScrollItemSize to specify the height of an item.
<p-autocomplete [(ngModel)]="selectedItem" [virtualScroll]="true" [suggestions]="filteredItems" [virtualScrollItemSize]="34" (completeMethod)="filterItems($event)" optionLabel="label" [dropdown]="true" />
Multiple mode is enabled using multiple property used to select more than one value from the autocomplete. In this case, value reference should be an array.
<label for="multiple-ac-1" class="font-bold mb-2 block">With Typeahead</label>
<p-autocomplete [(ngModel)]="value1" inputId="multiple-ac-1" multiple fluid [suggestions]="items" (completeMethod)="search($event)" />
<label for="multiple-ac-2" class="font-bold mt-8 mb-2 block">Without Typeahead</label>
<p-autocomplete [(ngModel)]="value2" inputId="multiple-ac-2" multiple fluid (completeMethod)="search($event)" [typeahead]="false" />
A floating label appears on top of the input field when focused. Visit FloatLabel documentation for more information.
<p-floatlabel>
<p-autocomplete [(ngModel)]="value1" [suggestions]="items" (completeMethod)="search($event)" inputId="over_label" />
<label for="over_label">Over Label</label>
</p-floatlabel>
<p-floatlabel variant="in">
<p-autocomplete [(ngModel)]="value2" [suggestions]="items" (completeMethod)="search($event)" inputId="in_label" />
<label for="in_label">In Label</label>
</p-floatlabel>
<p-floatlabel variant="on">
<p-autocomplete [(ngModel)]="value3" [suggestions]="items" (completeMethod)="search($event)" inputId="on_label" />
<label for="on_label">On Label</label>
</p-floatlabel>
IftaLabel is used to create infield top aligned labels. Visit IftaLabel documentation for more information.
<p-iftalabel>
<p-autocomplete [(ngModel)]="value" [suggestions]="items" (completeMethod)="search($event)" inputId="ac" />
<label for="ac">Identifier</label>
</p-iftalabel>
AutoComplete provides small and large sizes as alternatives to the base.
<p-autocomplete [(ngModel)]="value1" [suggestions]="items" (completeMethod)="search()" size="small" placeholder="Small" dropdown />
<p-autocomplete [(ngModel)]="value2" [suggestions]="items" (completeMethod)="search()" placeholder="Normal" dropdown />
<p-autocomplete [(ngModel)]="value3" [suggestions]="items" (completeMethod)="search()" size="large" placeholder="Large" dropdown />
Specify the variant property as filled to display the component with a higher visual emphasis than the default outlined style.
<p-autocomplete [(ngModel)]="selectedItem" [suggestions]="suggestions" (completeMethod)="search($event)" variant="filled" />
Invalid state style is added using the ng-invalid and ng-dirty class to indicate a failed validation.
<p-autocomplete class="ng-invalid ng-dirty" [(ngModel)]="selectedItem" [suggestions]="suggestions" (completeMethod)="search($event)" placeholder="Code" />
When disabled is present, the element cannot be edited and focused.
<p-autocomplete [(ngModel)]="selectedItem" [suggestions]="suggestions" placeholder="Disabled" (completeMethod)="search($event)" [disabled]="true" />
Value to describe the component can either be provided via label tag combined with inputId prop or using ariaLabelledBy, ariaLabel props. The input element has combobox role in addition to aria-autocomplete, aria-haspopup and aria-expanded attributes. The relation between the input and the popup is created with aria-controls and aria-activedescendant attribute is used to instruct screen reader which option to read during keyboard navigation within the popup list.
In multiple mode, chip list uses listbox role whereas each chip has the option role with aria-label set to the label of the chip.
The popup list has an id that refers to the aria-controls attribute of the input element and uses listbox as the role. Each list item has option role and an id to match the aria-activedescendant of the input element.
<label for="ac1">Username</label>
<p-autocomplete inputId="ac1"/>
<span id="ac2">Email</span>
<p-autocomplete ariaLabelledBy="ac2" />
<p-autocomplete ariaLabel="City" />
| Key | Function |
|---|---|
| tab | Moves focus to the input element when popup is not visible. If the popup is open and an item is highlighted then popup gets closed, item gets selected and focus moves to the next focusable element. |
| up arrow | Highlights the previous item if popup is visible. |
| down arrow | Highlights the next item if popup is visible. |
| enter | Selects the highlighted item and closes the popup if popup is visible. |
| home | Highlights the first item if popup is visible. |
| end | Highlights the last item if popup is visible. |
| escape | Hides the popup. |
| Key | Function |
|---|---|
| backspace | Deletes the previous chip if the input field is empty. |
| left arrow | Moves focus to the previous chip if available and input field is empty. |
| Key | Function |
|---|---|
| left arrow | Moves focus to the previous chip if available. |
| right arrow | Moves focus to the next chip, if there is none then input field receives the focus. |
| backspace | Deletes the chips and adds focus to the input field. |