AutoComplete

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

Import #


import { AutoComplete } 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)]="value" [suggestions]="items" (completeMethod)="search($event)" />

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" />
</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)]="value" [dropdown]="true" [suggestions]="items" (completeMethod)="search($event)" />

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)" optionLabel="name" />

Template #

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>

Group #

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>

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)" optionLabel="name" />

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

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.

With Typeahead

Without Typeahead


<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" />

Float Label #

A floating label appears on top of the input field when focused. Visit FloatLabel documentation for more information.

Over Label

In Label

On Label


<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>

Ifta Label #

IftaLabel is used to create infield top aligned labels. Visit IftaLabel documentation for more information.

Identifier


<p-iftalabel>
    <p-autocomplete [(ngModel)]="value" [suggestions]="items" (completeMethod)="search($event)" inputId="ac" />
    <label for="ac">Identifier</label>
</p-iftalabel>

Sizes #

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 />

Filled #

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 #

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" />

Disabled #

When disabled is present, the element cannot be edited and focused.


<p-autocomplete [(ngModel)]="selectedItem" [suggestions]="suggestions" placeholder="Disabled" (completeMethod)="search($event)" [disabled]="true" />

Accessibility #

Screen Reader

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" />

Keyboard Support

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.

Chips Input Keyboard Support

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.

Chip Keyboard Support

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.

name	type	default	description
minLength	number	1	Minimum number of characters to initiate a search.
delay	number	300	Delay between keystrokes to wait before sending a query.
style	Object	null	Inline style of the component.
panelStyle	Object	null	Inline style of the overlay panel element.
styleClass	string	null	Style class of the component.
panelStyleClass	string	null	Style class of the overlay panel element.
inputStyle	Object	null	Inline style of the input field.
inputId	string	null	Identifier of the focus input to match a label defined for the component.
inputStyleClass	string	null	Inline style of the input field.
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.
scrollHeight	string	200px	Maximum height of the suggestions panel.
lazy	boolean	false	Defines if data is loaded and interacted with in lazy manner.
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.
maxlength	number	null	Maximum number of character allows in the input field.
name	string	null	Name of the input element.
required	boolean	false	When present, it specifies that an input field must be filled out before submitting the form.
size	"small" \| "large"	null	Defines the size of the component.
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).
autoHighlight	boolean	false	When enabled, highlights the first item in the list by default.
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.
type	string	text	Type of the input, defaults to "text".
autoZIndex	boolean	true	Whether to automatically manage layering.
baseZIndex	number	0	Base zIndex value to use in layering.
ariaLabel	string	null	Defines a string that labels the input for accessibility.
dropdownAriaLabel	string	null	Defines a string that labels the dropdown button for accessibility.
ariaLabelledBy	string	null	Specifies one or more IDs in the DOM that labels the input field.
dropdownIcon	string	null	Icon class of the dropdown icon.
unique	boolean	true	Ensures uniqueness of selected items on multiple mode.
group	boolean	false	Whether to display options as grouped when nested options are provided.
completeOnFocus	boolean	false	Whether to run a query when input receives focus.
showClear	boolean	false	When enabled, a clear icon is displayed to clear the value.
field	string	null	Field of a suggested object to resolve and display.
dropdown	boolean	false	Displays a button next to the input field when enabled.
showEmptyMessage	boolean	true	Whether to show the empty message or not.
dropdownMode	string	blank	Specifies the behavior dropdown button. Default "blank" mode sends an empty string and "current" mode sends the input value.
multiple	boolean	false	Specifies if multiple values can be selected.
tabindex	number	null	Index of the element in tabbing order.
dataKey	string	null	A property to uniquely identify a value in options.
emptyMessage	string	null	Text to display when there is no data. Defaults to global value in i18n translation configuration.
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.
autofocus	boolean	false	When present, it specifies that the component should automatically get focus on load.
autocomplete	string	off	Used to define a string that autocomplete attribute the current element.
optionGroupChildren	string	items	Name of the options field of an option group.
optionGroupLabel	string	label	Name of the label field of an option group.
overlayOptions	OverlayOptions	null	Options for the overlay element.
suggestions	any[]	null	An array of suggestions to display.
itemSize	number	null	Element dimensions of option for virtual scrolling.
optionLabel	string \| Function	null	Property name or getter function to use as the label of an option.
optionValue	string \| Function	null	Property name or getter function to use as the value of an option.
id	string	null	Unique identifier of the component.
searchMessage	string	'{0} results are available'	Text to display when the search is active. Defaults to global value in i18n translation configuration.
emptySelectionMessage	string	'No selected item'	Text to display when filtering does not return any results. Defaults to global value in i18n translation configuration.
selectionMessage	string	'{0} items selected'	Text to be displayed in hidden accessible field when options are selected. Defaults to global value in i18n translation configuration.
autoOptionFocus	boolean	false	Whether to focus on the first visible or selected element when the overlay panel is shown.
selectOnFocus	boolean	false	When enabled, the focused option is selected.
searchLocale	boolean	false	Locale to use in searching. The default locale is the host environment's current locale.
optionDisabled	string	null	Property name or getter function to use as the disabled flag of an option, defaults to false when not defined.
focusOnHover	boolean	true	When enabled, the hovered option will be focused.
typeahead	boolean	true	Whether typeahead is active or not.
variant	"outlined" \| "filled"	outlined	Specifies the input variant of the component.
fluid	boolean	false	Spans 100% width of the container when enabled.

name	parameters	description
completeMethod	event : AutoCompleteCompleteEvent	Callback to invoke to search for suggestions.
onSelect	event : AutoCompleteSelectEvent	Callback to invoke when a suggestion is selected.
onUnselect	event : AutoCompleteUnselectEvent	Callback to invoke when a selected value is removed.
onFocus	event : Event	Callback to invoke when the component receives focus.
onBlur	event : Event	Callback to invoke when the component loses focus.
onDropdownClick	event : AutoCompleteDropdownClickEvent	Callback to invoke to when dropdown button is clicked.
onClear	event : Event	Callback to invoke when clear button is clicked.
onKeyUp	event : KeyboardEvent	Callback to invoke on input key up.
onShow	event : Event	Callback to invoke on overlay is shown.
onHide	event : Event	Callback to invoke on overlay is hidden.
onLazyLoad	event : AutoCompleteLazyLoadEvent	Callback to invoke on lazy load data.

name	parameters	description
item	context : { $implicit: any, // Option. index: number, // Option index. }	Custom item template.
group	context : { $implicit: any, // Option group. }	Custom group template.
selectedItem	context : { $implicit: any, // Selected value. }	Custom selected item template, only supported in multiple mode.
header		Custom header template.
empty		Custom empty template.
footer		Custom footer template.
loader	context : { $implicit: ScrollerOptions, // Virtual scroller options. }	Custom loader template.
removetokenicon		Custom remove token icon template.
loadingicon		Custom loading icon template.
clearicon		Custom clear icon template.
dropdownicon		Custom dropdown icon template.

name	type	description
originalEvent	Event	Browser event.
query	string	Selected option value.

name	type	description
originalEvent	Event	Browser event.
query	string	Selected option value.

AutoComplete

Import #

Basic #

Reactive Forms #

Dropdown #

Objects #

Template #

Group #

Force Selection #

Virtual Scroll #

Multiple #

Float Label #

Ifta Label #

Sizes #

Filled #

Invalid #

Disabled #

Accessibility #

Screen Reader

Keyboard Support

Chips Input Keyboard Support

Chip Keyboard Support

AutoComplete API

AutoComplete #

Properties #

Emitters #

Templates #

Events #

AutoCompleteCompleteEvent #

AutoCompleteDropdownClickEvent #

AutoCompleteSelectEvent #

AutoCompleteUnselectEvent #

AutoCompleteLazyLoadEvent #

AutoComplete Theming

CSS Classes #

AutoComplete Design Tokens #

name	type	description
first	any	First element in viewport.
last	any	Last element in viewport.

class	description
p-autocomplete	Class name of the root element
p-autocomplete-input	Class name of the input element
p-autocomplete-input-multiple	Class name of the input multiple element
p-autocomplete-chip-item	Class name of the chip item element
p-autocomplete-chip	Class name of the chip element
p-autocomplete-chip-icon	Class name of the chip icon element
p-autocomplete-input-chip	Class name of the input chip element
p-autocomplete-loader	Class name of the loader element
p-autocomplete-dropdown	Class name of the dropdown element
p-autocomplete-overlay	Class name of the panel element
p-autocomplete-list	Class name of the list element
p-autocomplete-option-group	Class name of the option group element
p-autocomplete-option	Class name of the option element
p-autocomplete-empty-message	Class name of the empty message element

token	variable	description
autocomplete.background	--p-autocomplete-background	Background of root
autocomplete.disabled.background	--p-autocomplete-disabled-background	Disabled background of root
autocomplete.filled.background	--p-autocomplete-filled-background	Filled background of root
autocomplete.filled.hover.background	--p-autocomplete-filled-hover-background	Filled hover background of root
autocomplete.filled.focus.background	--p-autocomplete-filled-focus-background	Filled focus background of root
autocomplete.border.color	--p-autocomplete-border-color	Border color of root
autocomplete.hover.border.color	--p-autocomplete-hover-border-color	Hover border color of root
autocomplete.focus.border.color	--p-autocomplete-focus-border-color	Focus border color of root
autocomplete.invalid.border.color	--p-autocomplete-invalid-border-color	Invalid border color of root
autocomplete.color	--p-autocomplete-color	Color of root
autocomplete.disabled.color	--p-autocomplete-disabled-color	Disabled color of root
autocomplete.placeholder.color	--p-autocomplete-placeholder-color	Placeholder color of root
autocomplete.invalid.placeholder.color	--p-autocomplete-invalid-placeholder-color	Invalid placeholder color of root
autocomplete.shadow	--p-autocomplete-shadow	Shadow of root
autocomplete.padding.x	--p-autocomplete-padding-x	Padding x of root
autocomplete.padding.y	--p-autocomplete-padding-y	Padding y of root
autocomplete.border.radius	--p-autocomplete-border-radius	Border radius of root
autocomplete.focus.ring.width	--p-autocomplete-focus-ring-width	Focus ring width of root
autocomplete.focus.ring.style	--p-autocomplete-focus-ring-style	Focus ring style of root
autocomplete.focus.ring.color	--p-autocomplete-focus-ring-color	Focus ring color of root
autocomplete.focus.ring.offset	--p-autocomplete-focus-ring-offset	Focus ring offset of root
autocomplete.focus.ring.shadow	--p-autocomplete-focus-ring-shadow	Focus ring shadow of root
autocomplete.transition.duration	--p-autocomplete-transition-duration	Transition duration of root
autocomplete.overlay.background	--p-autocomplete-overlay-background	Background of overlay
autocomplete.overlay.border.color	--p-autocomplete-overlay-border-color	Border color of overlay
autocomplete.overlay.border.radius	--p-autocomplete-overlay-border-radius	Border radius of overlay
autocomplete.overlay.color	--p-autocomplete-overlay-color	Color of overlay
autocomplete.overlay.shadow	--p-autocomplete-overlay-shadow	Shadow of overlay
autocomplete.list.padding	--p-autocomplete-list-padding	Padding of list
autocomplete.list.gap	--p-autocomplete-list-gap	Gap of list
autocomplete.option.focus.background	--p-autocomplete-option-focus-background	Focus background of option
autocomplete.option.selected.background	--p-autocomplete-option-selected-background	Selected background of option
autocomplete.option.selected.focus.background	--p-autocomplete-option-selected-focus-background	Selected focus background of option
autocomplete.option.color	--p-autocomplete-option-color	Color of option
autocomplete.option.focus.color	--p-autocomplete-option-focus-color	Focus color of option
autocomplete.option.selected.color	--p-autocomplete-option-selected-color	Selected color of option
autocomplete.option.selected.focus.color	--p-autocomplete-option-selected-focus-color	Selected focus color of option
autocomplete.option.padding	--p-autocomplete-option-padding	Padding of option
autocomplete.option.border.radius	--p-autocomplete-option-border-radius	Border radius of option
autocomplete.option.group.background	--p-autocomplete-option-group-background	Background of option group
autocomplete.option.group.color	--p-autocomplete-option-group-color	Color of option group
autocomplete.option.group.font.weight	--p-autocomplete-option-group-font-weight	Font weight of option group
autocomplete.option.group.padding	--p-autocomplete-option-group-padding	Padding of option group
autocomplete.dropdown.width	--p-autocomplete-dropdown-width	Width of dropdown
autocomplete.dropdown.sm.width	--p-autocomplete-dropdown-sm-width	Sm width of dropdown
autocomplete.dropdown.lg.width	--p-autocomplete-dropdown-lg-width	Lg width of dropdown
autocomplete.dropdown.border.color	--p-autocomplete-dropdown-border-color	Border color of dropdown
autocomplete.dropdown.hover.border.color	--p-autocomplete-dropdown-hover-border-color	Hover border color of dropdown
autocomplete.dropdown.active.border.color	--p-autocomplete-dropdown-active-border-color	Active border color of dropdown
autocomplete.dropdown.border.radius	--p-autocomplete-dropdown-border-radius	Border radius of dropdown
autocomplete.dropdown.focus.ring.width	--p-autocomplete-dropdown-focus-ring-width	Focus ring width of dropdown
autocomplete.dropdown.focus.ring.style	--p-autocomplete-dropdown-focus-ring-style	Focus ring style of dropdown
autocomplete.dropdown.focus.ring.color	--p-autocomplete-dropdown-focus-ring-color	Focus ring color of dropdown
autocomplete.dropdown.focus.ring.offset	--p-autocomplete-dropdown-focus-ring-offset	Focus ring offset of dropdown
autocomplete.dropdown.focus.ring.shadow	--p-autocomplete-dropdown-focus-ring-shadow	Focus ring shadow of dropdown
autocomplete.dropdown.background	--p-autocomplete-dropdown-background	Background of dropdown
autocomplete.dropdown.hover.background	--p-autocomplete-dropdown-hover-background	Hover background of dropdown
autocomplete.dropdown.active.background	--p-autocomplete-dropdown-active-background	Active background of dropdown
autocomplete.dropdown.color	--p-autocomplete-dropdown-color	Color of dropdown
autocomplete.dropdown.hover.color	--p-autocomplete-dropdown-hover-color	Hover color of dropdown
autocomplete.dropdown.active.color	--p-autocomplete-dropdown-active-color	Active color of dropdown
autocomplete.chip.border.radius	--p-autocomplete-chip-border-radius	Border radius of chip
autocomplete.chip.focus.background	--p-autocomplete-chip-focus-background	Focus background of chip
autocomplete.chip.focus.color	--p-autocomplete-chip-focus-color	Focus color of chip
autocomplete.empty.message.padding	--p-autocomplete-empty-message-padding	Padding of empty message