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)]="selectedItem" [suggestions]="suggestions" (completeMethod)="search($event)"></p-autoComplete>
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>
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>
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>
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>
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>
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 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 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>
Following is the list of structural style classes, for theming classes visit theming page.
Name | Element |
---|---|
p-autocomplete | Container element |
p-autocomplete-panel | Overlay panel of suggestions. |
p-autocomplete-items | List container of suggestions. |
p-autocomplete-item | List item of a suggestion. |
p-autocomplete-token | Element of a selected item in multiple mode. |
p-autocomplete-token-icon | Close icon element of a selected item in multiple mode. |
p-autocomplete-token-label | Label of a selected item in multiple mode. |
p-autocomplete-loader | Loader icon. |
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>
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. |
API defines helper props, events and others for the PrimeNG AutoComplete module.
Name | Type | Default | Description |
---|---|---|---|
suggestions | array | null | An array of suggestions to display. |
field | any | null | Field of a suggested object to resolve and display. |
scrollHeight | string | 200px | Maximum height of the suggestions panel. |
dropdown | boolean | false | Displays a button next to the input field when enabled. |
multiple | boolean | false | Specifies if multiple values can be selected. |
dropdownIcon | string | null | Icon class of the dropdown icon. |
minLength | number | 1 | Minimum number of characters to initiate a search. |
delay | number | 300 | Delay between keystrokes to wait before sending a query. |
completeOnFocus | boolean | false | Whether to run a query when input receives focus. |
style | string | null | Inline style of the component. |
inputStyle | string | null | Inline style of the input field. |
panelStyle | string | null | Inline style of the overlay panel element. |
styleClass | string | null | Style class of the component. |
inputStyleClass | string | null | Inline style of the input field. |
panelStyleClass | string | null | Style class of the overlay panel element. |
inputId | string | null | Identifier of the focus input to match a label defined for the component. |
name | string | null | Name of the input element. |
optionGroupLabel | string | label | Name of the label field of an option group. |
group | boolean | false | Whether to display options as grouped when nested options are provided. |
optionGroupChildren | string | items | Name of the options field of an option group. |
placeholder | string | null | Hint text for the input field. |
readonly | boolean | false | When present, it specifies that the input cannot be typed. |
disabled | boolean | false | When present, it specifies that the component should be disabled. |
maxlength | number | null | Maximum number of character allows in the input field. |
size | number | null | Size of the input field. |
appendTo | any | null | Target element to attach the overlay, valid values are "body" or a local ng-template variable of another element (note: use binding with brackets for template variables, e.g. [appendTo]="mydiv" for a div element having #mydiv as variable name). |
tabindex | number | null | Index of the element in tabbing order. |
dataKey | string | null | A property to uniquely identify a value in options. |
autoHighlight | boolean | false | When enabled, highlights the first item in the list by default. |
type | string | text | Type of the input, defaults to "text". |
showEmptyMessage | boolean | false | Whether to show the empty message or not. |
emptyMessage | string | No results found | Text to display when there is no data. Defaults to global value in i18n translation configuration. |
immutable | boolean | true | Defines how the suggestions should be manipulated. More information is available at "Change Detection" section above. |
required | boolean | false | When present, it specifies that an input field must be filled out before submitting the form. |
autofocus | boolean | false | When present, it specifies that the component should automatically get focus on load. |
forceSelection | boolean | false | When present, autocomplete clears the manual input if it does not match of the suggestions to force only accepting values from the suggestions. |
dropdownMode | string | blank | Specifies the behavior dropdown button. Default "blank" mode sends an empty string and "current" mode sends the input value. |
baseZIndex | number | 0 | Base zIndex value to use in layering. |
autoZIndex | boolean | true | Whether to automatically manage layering. |
showTransitionOptions | string | .12s cubic-bezier(0, 0, 0.2, 1) | Transition options of the show animation. |
hideTransitionOptions | string | .1s linear | Transition options of the hide animation. |
ariaLabel | string | null | Defines a string that labels the input for accessibility. |
ariaLabelledBy | string | null | Specifies one or more IDs in the DOM that labels the input field. |
dropdownAriaLabel | string | null | Defines a string that labels the dropdown button for accessibility. |
unique | boolean | true | Ensures uniqueness of selected items on multiple mode. |
autocomplete | string | null | Used to define a string that autocomplete attribute the current element. |
showClear | boolean | false | When enabled, a clear icon is displayed to clear the value. |
virtualScroll | boolean | false | Whether the data should be loaded on demand during scroll. |
virtualScrollItemSize | number | null | Height of an item in the list for VirtualScrolling. |
virtualScrollOptions | ScrollerOptions | null | Whether to use the scroller feature. The properties of scroller component can be used like an object in it. |
lazy | boolean | false | Defines if data is loaded and interacted with in lazy manner. |
Name | Parameters | Description |
---|---|---|
completeMethod | event.originalEvent: browser event event.query: Value to search with | Callback to invoke to search for suggestions. |
onFocus | event: Browser event | Callback to invoke when autocomplete gets focus. |
onBlur | event: Browser event | Callback to invoke when autocomplete loses focus. |
onKeyUp | event: Browser event | Callback to invoke when a user releases a key. |
onSelect | value: Selected value | Callback to invoke when a suggestion is selected. |
onUnselect | value: Unselected value in multiple mode | Callback to invoke when a selected value is removed. |
onDropdownClick | event.originalEvent: browser event event.query: Current value of the input field | Callback to invoke when dropdown button is clicked. |
onClear | - | Callback to invoke when input field is cleared. |
onShow | event: Animation event | Callback to invoke when autocomplete overlay gets visible. |
onHide | - | Callback to invoke when autocomplete overlay gets hidden. |
onLazyLoad | event.first: First index of the new data range to be loaded. event.last: Last index of the new data range to be loaded. | Callback to invoke in lazy mode to load new data. |
Name | Parameters |
---|---|
item | - |
group | $implicit: optgroup |
selectedItem | $implicit: value |
header | - |
empty | - |
footer | - |
loader | - |
removetokenicon | - |
loadingicon | - |
clearicon | - |
dropdownicon | - |