AutoComplete

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


import AutoComplete from 'primevue/autocomplete';

AutoComplete is used as a controlled component with v-model property. In addition, suggestions property and a complete method are required to query the results.

No results found

<AutoComplete v-model="value" :suggestions="items" @complete="search" />

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.

No results found

<AutoComplete v-model="value" dropdown :suggestions="items" @complete="search" />

AutoComplete can work with objects using the optionLabel 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"}.

No results found

<AutoComplete v-model="selectedCountry" optionLabel="name" :suggestions="filteredCountries" @complete="search" />

Item template allows displaying custom content inside the suggestions panel. The slotProps variable passed to the template provides an item property to represent an item in the suggestions collection. In addition optiongroup, chip, header and footer slots are provided for further customization

No results found

<AutoComplete v-model="selectedCountry" optionLabel="name" :suggestions="filteredCountries" @complete="search">
    <template #option="slotProps">
        <div class="flex align-options-center">
            <img :alt="slotProps.option.name" src="https://primefaces.org/cdn/primevue/images/flag/flag_placeholder.png" :class="`flag flag-${slotProps.option.code.toLowerCase()} mr-2`" style="width: 18px" />
            <div>{{ slotProps.option.name }}</div>
        </div>
    </template>
</AutoComplete>

Option groups are specified with the optionGroupLabel and optionGroupChildren properties.

No results found

<AutoComplete v-model="selectedCity" :suggestions="filteredCities" @complete="search" optionLabel="label" optionGroupLabel="label" optionGroupChildren="items" placeholder="Hint: type 'a'">
    <template #optiongroup="slotProps">
        <div class="flex align-items-center country-item">
            <img :alt="slotProps.item.label" src="https://primefaces.org/cdn/primevue/images/flag/flag_placeholder.png" :class="`flag flag-${slotProps.item.code.toLowerCase()} mr-2`" style="width: 18px" />
            <div>{{ slotProps.item.label }}</div>
        </div>
    </template>
</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. Simply enable forceSelection to enforce that input is always from the suggestion list.

No results found

<AutoComplete v-model="value" :suggestions="items" @complete="search" forceSelection />

Virtual Scrolling is a performant way to render large lists. Configuration of the scroll behavior is defined with virtualScrollerOptions that requires itemSize as the mandatory value to set the height of an item. Visit VirtualScroller documentation for more information about the configuration API.

No results found

<AutoComplete v-model="selectedItem" :suggestions="filteredItems" @complete="searchItems"
    :virtualScrollerOptions="{ itemSize: 38 }" optionLabel="label" dropdown />

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.

No results found

<AutoComplete v-model="value" multiple :suggestions="items" @complete="search" />

A floating label appears on top of the input field when focused.

No results found

<span class="p-float-label">
    <AutoComplete v-model="value" inputId="ac" :suggestions="items" @complete="search" />
    <label for="ac">Float Label</label>
</span>

Invalid state style is added using the p-invalid class to indicate a failed validation.

No results found

<AutoComplete v-model="value" :suggestions="items" @complete="search" class="p-invalid" />

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

No results found

<AutoComplete disabled placeholder="Disabled" />

Compatibility with popular Vue form libraries.

VeeValidate is a popular library for handling forms in Vue.

No results found
 

<template>
    <div class="card flex justify-content-center">
        <form @submit="onSubmit" class="flex flex-column gap-2">
            <label for="ac">Value</label>
            <AutoComplete v-model="value" :inputClass="{ 'p-invalid': errorMessage }" inputId="ac" :suggestions="items" @complete="search" aria-describedby="ac-error" />
            <small class="p-error" id="ac-error">{{ errorMessage || '&nbsp;' }}</small>
            <Button type="submit" label="Submit" />
        </form>
    </div>
</template>

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 with aria-orientation set to horizontal 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>
<AutoComplete inputId="ac1" />

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

<AutoComplete aria-label="City" />

Closed State Keyboard Support

KeyFunction
tabMoves focus to the autocomplete element.
any printable characterOpens the popup and moves focus to the first option.

Popup Keyboard Support

KeyFunction
tabMoves focus to the next focusable element in the popup. If there is none, the focusable option is selected and the overlay is closed then moves focus to next element in page.
shift + tabMoves focus to the previous focusable element in the popup. If there is none, the focusable option is selected and the overlay is closed then moves focus to next element in page.
enterSelects the focused option and closes the popup, then moves focus to the autocomplete element.
spaceSelects the focused option and closes the popup, then moves focus to the autocomplete element.
escapeCloses the popup, then moves focus to the autocomplete element.
down arrowMoves focus to the next option, if there is none then visual focus does not change.
up arrowMoves focus to the previous option, if there is none then visual focus does not change.
alt + up arrowSelects the focused option and closes the popup, then moves focus to the autocomplete element.
left arrowRemoves the visual focus from the current option and moves input cursor to one character left.
right arrowRemoves the visual focus from the current option and moves input cursor to one character right.
homeMoves input cursor at the end, if not then moves focus to the first option.
endMoves input cursor at the beginning, if not then moves focus to the last option.
pageUpJumps visual focus to first option.
pageDownJumps visual focus to last option.

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.