import AutoComplete from 'primevue/autocomplete';
<script src="https://unpkg.com/primevue@^3/core/core.js"></script>
<script src="https://unpkg.com/primevue@^3/autocomplete/autocomplete.min.js"></script>
AutoComplete uses v-model for two-way binding, requires a list of suggestions and a complete method to query for the results. The complete method gets the query text as event.query property and should update the suggestions with the search results. Example below connects to a remote datasource to fetch the results;
<AutoComplete v-model="selectedCountry" :suggestions="filteredCountriesBasic" @complete="searchCountry($event)" field="name" />
export default {
data() {
return {
selectedCountry: null,
filteredCountries: null
}
},
countryService: null,
created() {
this.countryService = new CountryService();
},
methods: {
searchCountry(event) {
this.filteredCountriesBasic = this.countryService.search(event.query);
}
}
}
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.
<AutoComplete v-model="brand" :dropdown="true" :suggestions="filteredBrands" @complete="searchBrand($event)" placeholder="Hint: type 'v' or 'f'" />
Multiple mode is enabled using multiple property to select more than one value from the autocomplete. In this case, value reference should be an array.
<AutoComplete :multiple="true" v-model="selectedCountries" :suggestions="filteredCountriesMultiple" @complete="searchCountryMultiple($event)" field="name" />
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"}.
<AutoComplete field="label" v-model="selectedCountry" :suggestions="filteredCountriesBasic" @complete="searchCountryBasic($event)" />
Options groups are specified with the optionGroupLabel and optionGroupChildren properties.
export default {
data() {
return {
selectedGroupedCity: null,
groupedCities: [{
label: 'Germany', code: 'DE',
items: [
{label: 'Berlin', value: 'Berlin'},
{label: 'Frankfurt', value: 'Frankfurt'},
{label: 'Hamburg', value: 'Hamburg'},
{label: 'Munich', value: 'Munich'}
]
},
{
label: 'USA', code: 'US',
items: [
{label: 'Chicago', value: 'Chicago'},
{label: 'Los Angeles', value: 'Los Angeles'},
{label: 'New York', value: 'New York'},
{label: 'San Francisco', value: 'San Francisco'}
]
},
{
label: 'Japan', code: 'JP',
items: [
{label: 'Kyoto', value: 'Kyoto'},
{label: 'Osaka', value: 'Osaka'},
{label: 'Tokyo', value: 'Tokyo'},
{label: 'Yokohama', value: 'Yokohama'}
]
}]
}
}
}
<AutoComplete v-model="selectedCity" :suggestions="filteredCities" @complete="searchCity($event)"
field="label" optionGroupLabel="label" optionGroupChildren="items"></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.
<AutoComplete forceSelection v-model="brand" :suggestions="filteredBrands" @complete="searchBrand($event)" />
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
<AutoComplete v-model="brand" :suggestions="filteredBrands" @complete="searchBrand($event)" placeholder="Hint: type 'v' or 'f'" :dropdown="true">
<template #item="slotProps">
<img :alt="slotProps.item" :src="'demo/images/car/' + slotProps.item + '.png'" />
<div>{{slotProps.item}}</div>
</template>
</AutoComplete>
Any property such as name and placeholder are passed to the underlying input element. Following are the additional properties to configure the component.
| Name | Type | Default | Description |
|---|---|---|---|
| modelValue | any | null | Value of the component. |
| suggestions | array | null | An array of suggestions to display. |
| field | any | null | Property name or getter function of a suggested object to resolve and display. |
| optionGroupLabel | string | null | Property name or getter function to use as the label of an option group. |
| optionGroupChildren | string | null | Property name or getter function that refers to the children options of option group. |
| scrollHeight | string | 200px | Maximum height of the suggestions panel. |
| dropdown | boolean | false | Displays a button next to the input field when enabled. |
| dropdownMode | string | blank | Specifies the behavior dropdown button. Default "blank" mode sends an empty string and "current" mode sends the input value. |
| autoHighlight | boolean | false | Highlights automatically the first item of the dropdown to be selected. |
| multiple | boolean | false | Specifies if multiple values can be selected. |
| minLength | number | 1 | Minimum number of characters to initiate a search. |
| completeOnFocus | boolean | false | Whether to run a query when input receives focus. |
| delay | number | 300 | Delay between keystrokes to wait before sending a query. |
| appendTo | string | body | A valid query selector or an HTMLElement to specify where the overlay gets attached. Special keywords are "body" for document body and "self" for the element itself. |
| 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. |
| inputStyle | any | null | Inline style of the input field. |
| inputClass | string | null | Style class of the input field. |
| style | any | null | Style class of the component input field. |
| class | string | null | Inline style of the component. |
| panelClass | string | null | Style class of the overlay panel. |
| virtualScrollerOptions | object | null | Whether to use the virtualScroller feature. The properties of |
Any valid event such as focus, blur and input are passed to the underlying input element. Following are the additional events to configure the component.
| Name | Parameters | Description |
|---|---|---|
| complete |
event.originalEvent: Browser event event.query: Value to search with |
Callback to invoke to search for suggestions. |
| item-select | event.originalEvent: Browser event event.value: Selected item |
Callback to invoke when a suggestion is selected. |
| item-unselect | event.originalEvent: Browser event event.value: Unselected item |
Callback to invoke when a selected value is removed. |
| dropdown-click |
event.originalEvent: browser event event.query: Current value of the input field |
Callback to invoke to when dropdown button is clicked. |
| clear | - | Callback to invoke when input is cleared by the user. |
| Name | Parameters |
|---|---|
| item | item: Option instance index: Index of the option |
| optiongroup | item: OptionGroup instance index: Index of the option group |
| header | value: Value of the component suggestions: Displayed options |
| footer | value: Value of the component suggestions: Displayed options |
| chip | value: A value in the selection |
| content | items: An array of objects to display for virtualscroller styleClass: Style class of the component contentRef: Referance of the content getItemOptions: Options of the items |
| loader | options: Options of the loader items for virtualscroller |
Following is the list of structural style classes
| 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. |
None.