AutoComplete

AutoComplete is an input component that provides real-time suggestions when being typed.

Import #


import { AutoCompleteModule } from 'primeng/autocomplete';

Basic #

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)]="selectedItem" [suggestions]="suggestions" (completeMethod)="search($event)"></p-autoComplete>

Reactive Forms #

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"></p-autoComplete>
</form>

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)]="selectedCountry" [dropdown]="true" [suggestions]="filteredCountries" (completeMethod)="filterCountry($event)" field="name"></p-autoComplete>

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)]="selectedCountry" [suggestions]="filteredCountries" (completeMethod)="filterCountry($event)" field="name"></p-autoComplete>

Template #

item 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)]="selectedCountryAdvanced" [suggestions]="filteredCountries" 
    (completeMethod)="filterCountry($event)" field="name" [dropdown]="true">
        <ng-template let-country pTemplate="item">
            <div class="flex align-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>
</p-autoComplete>

Grouped #

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)" field="label" [dropdown]="true">
    <ng-template let-group pTemplate="group">
        <div class="flex align-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>

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)]="selectedCountry" [forceSelection]="true" [suggestions]="filteredCountries" (completeMethod)="filterCountry($event)" field="name"></p-autoComplete>

Virtual Scroll #

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)" field="label" [dropdown]="true"> </p-autoComplete>

Multiple #

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.



<span class="p-fluid">
    <p-autoComplete [(ngModel)]="selectedCountries" [suggestions]="filteredCountries" 
        (completeMethod)="filterCountry($event)" field="name" [multiple]="true"></p-autoComplete>
</span>

Style #

Following is the list of structural style classes, for theming classes visit theming page.

NameElement
p-autocompleteContainer element
p-autocomplete-panelOverlay panel of suggestions.
p-autocomplete-itemsList container of suggestions.
p-autocomplete-itemList item of a suggestion.
p-autocomplete-tokenElement of a selected item in multiple mode.
p-autocomplete-token-iconClose icon element of a selected item in multiple mode.
p-autocomplete-token-labelLabel of a selected item in multiple mode.
p-autocomplete-loaderLoader icon.
Accessibility guide documents the specification of this component based on WCAG guidelines, the implementation is in progress.

Accessibility #

Screen Reader

Value to describe the component can either be provided via label tag combined with inputId prop or using aria-labelledby, aria-label 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"></p-autoComplete>

<span id="ac2">Email</span>
<p-autoComplete aria-labelledby="ac2"></p-autoComplete>

<p-autoComplete aria-label="City"></p-autoComplete>

Keyboard Support

KeyFunction
tabMoves 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 arrowHighlights the previous item if popup is visible.
down arrowHighlights the next item if popup is visible.
enterSelects the highlighted item and closes the popup if popup is visible.
homeHighlights the first item if popup is visible.
endHighlights the last item if popup is visible.
escapeHides the popup.

Chips Input Keyboard Support

KeyFunction
backspaceDeletes the previous chip if the input field is empty.
left arrowMoves focus to the previous chip if available and input field is empty.

Chip Keyboard Support

KeyFunction
left arrowMoves focus to the previous chip if available.
right arrowMoves focus to the next chip, if there is none then input field receives the focus.
backspaceDeletes the chips and adds focus to the input field.
PrimeNG 16.0.0-rc.2 by PrimeTek