Form

AutoComplete

A text box that suggests as you type, with suggestions supplied by your app, single or multiple values as chips, and a button for the whole list.

WAI-ARIA tested

Import

main.ts

import { AutoComplete } from '@vitral/vue';

Basic

Country

Value: null

1<script setup lang="ts">2import { AutoComplete, FilterService, Label, StackPanel } from '@vitral/vue';3import { ref } from 'vue';4 5interface Country {6    name: string;7    code: string;8    region: string;9}10 11const countries: Country[] = [12    { name: 'Angola', code: 'AO', region: 'Africa' },13    { name: 'Argentina', code: 'AR', region: 'Americas' },14    { name: 'Brazil', code: 'BR', region: 'Americas' },15    { name: 'Cabo Verde', code: 'CV', region: 'Africa' },16    { name: 'Canada', code: 'CA', region: 'Americas' },17    { name: 'Chile', code: 'CL', region: 'Americas' },18    { name: 'Colombia', code: 'CO', region: 'Americas' },19    { name: 'France', code: 'FR', region: 'Europe' },20    { name: 'Germany', code: 'DE', region: 'Europe' },21    { name: 'Moçambique', code: 'MZ', region: 'Africa' },22    { name: 'Peru', code: 'PE', region: 'Americas' },23    { name: 'Portugal', code: 'PT', region: 'Europe' },24    { name: 'Spain', code: 'ES', region: 'Europe' },25    { name: 'São Tomé and Príncipe', code: 'ST', region: 'Africa' },26    { name: 'Uruguay', code: 'UY', region: 'Americas' }27];28 29const match = (query: string) => countries.filter((c) => FilterService.matches(c.name, query, 'contains'));30 31const single = ref<Country | string | null>(null);32const suggestions = ref<Country[]>([]);33</script>34 35<template>36    <StackPanel spacing="0.375rem" style="min-width: 16rem">37        <Label for="ac-country">Country</Label>38        <AutoComplete39            id="ac-country"40            v-model="single"41            :suggestions="suggestions"42            option-label="name"43            placeholder="Type a country"44            @complete="suggestions = match($event.query)"45        />46        <small style="color: var(--vt-text-muted-color)">Value: {{ typeof single === 'string' ? `"${single}"` : (single?.code ?? 'null') }}</small>47    </StackPanel>48</template>

Dropdown and forced selection

Country (from the list only)

1<script setup lang="ts">2import { AutoComplete, FilterService, Label, StackPanel } from '@vitral/vue';3import { ref } from 'vue';4 5interface Country {6    name: string;7    code: string;8    region: string;9}10 11const countries: Country[] = [12    { name: 'Angola', code: 'AO', region: 'Africa' },13    { name: 'Argentina', code: 'AR', region: 'Americas' },14    { name: 'Brazil', code: 'BR', region: 'Americas' },15    { name: 'Cabo Verde', code: 'CV', region: 'Africa' },16    { name: 'Canada', code: 'CA', region: 'Americas' },17    { name: 'Chile', code: 'CL', region: 'Americas' },18    { name: 'Colombia', code: 'CO', region: 'Americas' },19    { name: 'France', code: 'FR', region: 'Europe' },20    { name: 'Germany', code: 'DE', region: 'Europe' },21    { name: 'Moçambique', code: 'MZ', region: 'Africa' },22    { name: 'Peru', code: 'PE', region: 'Americas' },23    { name: 'Portugal', code: 'PT', region: 'Europe' },24    { name: 'Spain', code: 'ES', region: 'Europe' },25    { name: 'São Tomé and Príncipe', code: 'ST', region: 'Africa' },26    { name: 'Uruguay', code: 'UY', region: 'Americas' }27];28 29const match = (query: string) => countries.filter((c) => FilterService.matches(c.name, query, 'contains'));30 31const single = ref<Country | string | null>(null);32const suggestions = ref<Country[]>([]);33</script>34 35<template>36    <StackPanel spacing="0.375rem" style="min-width: 16rem">37        <Label for="ac-forced">Country (from the list only)</Label>38        <AutoComplete39            id="ac-forced"40            v-model="single"41            :suggestions="suggestions"42            option-label="name"43            dropdown44            force-selection45            show-clear46            @complete="suggestions = match($event.query)"47        />48    </StackPanel>49</template>

Multiple

Countries

1<script setup lang="ts">2import { AutoComplete, FilterService, Label, StackPanel } from '@vitral/vue';3import { ref } from 'vue';4 5interface Country {6    name: string;7    code: string;8    region: string;9}10 11const countries: Country[] = [12    { name: 'Angola', code: 'AO', region: 'Africa' },13    { name: 'Argentina', code: 'AR', region: 'Americas' },14    { name: 'Brazil', code: 'BR', region: 'Americas' },15    { name: 'Cabo Verde', code: 'CV', region: 'Africa' },16    { name: 'Canada', code: 'CA', region: 'Americas' },17    { name: 'Chile', code: 'CL', region: 'Americas' },18    { name: 'Colombia', code: 'CO', region: 'Americas' },19    { name: 'France', code: 'FR', region: 'Europe' },20    { name: 'Germany', code: 'DE', region: 'Europe' },21    { name: 'Moçambique', code: 'MZ', region: 'Africa' },22    { name: 'Peru', code: 'PE', region: 'Americas' },23    { name: 'Portugal', code: 'PT', region: 'Europe' },24    { name: 'Spain', code: 'ES', region: 'Europe' },25    { name: 'São Tomé and Príncipe', code: 'ST', region: 'Africa' },26    { name: 'Uruguay', code: 'UY', region: 'Americas' }27];28 29const match = (query: string) => countries.filter((c) => FilterService.matches(c.name, query, 'contains'));30 31const many = ref<Country[]>([]);32const suggestions = ref<Country[]>([]);33</script>34 35<template>36    <StackPanel spacing="0.375rem" style="min-width: 22rem">37        <Label for="ac-many">Countries</Label>38        <AutoComplete id="ac-many" v-model="many" :suggestions="suggestions" option-label="name" multiple fluid @complete="suggestions = match($event.query)" />39    </StackPanel>40</template>

Groups and templates

Country by region

1<script setup lang="ts">2import { AutoComplete, FilterService, Label, StackPanel } from '@vitral/vue';3import { ref } from 'vue';4 5interface Country {6    name: string;7    code: string;8    region: string;9}10 11const countries: Country[] = [12    { name: 'Angola', code: 'AO', region: 'Africa' },13    { name: 'Argentina', code: 'AR', region: 'Americas' },14    { name: 'Brazil', code: 'BR', region: 'Americas' },15    { name: 'Cabo Verde', code: 'CV', region: 'Africa' },16    { name: 'Canada', code: 'CA', region: 'Americas' },17    { name: 'Chile', code: 'CL', region: 'Americas' },18    { name: 'Colombia', code: 'CO', region: 'Americas' },19    { name: 'France', code: 'FR', region: 'Europe' },20    { name: 'Germany', code: 'DE', region: 'Europe' },21    { name: 'Moçambique', code: 'MZ', region: 'Africa' },22    { name: 'Peru', code: 'PE', region: 'Americas' },23    { name: 'Portugal', code: 'PT', region: 'Europe' },24    { name: 'Spain', code: 'ES', region: 'Europe' },25    { name: 'São Tomé and Príncipe', code: 'ST', region: 'Africa' },26    { name: 'Uruguay', code: 'UY', region: 'Americas' }27];28 29const match = (query: string) => countries.filter((c) => FilterService.matches(c.name, query, 'contains'));30 31const grouped = ref<Country | null>(null);32const groupedSuggestions = ref<{ region: string; items: Country[] }[]>([]);33function searchGrouped(query: string) {34    const hits = match(query);35    groupedSuggestions.value = ['Africa', 'Americas', 'Europe']36        .map((region) => ({ region, items: hits.filter((c) => c.region === region) }))37        .filter((g) => g.items.length);38}39</script>40 41<template>42    <StackPanel spacing="0.375rem" style="min-width: 16rem">43        <Label for="ac-grouped">Country by region</Label>44        <AutoComplete45            id="ac-grouped"46            v-model="grouped"47            :suggestions="groupedSuggestions"48            option-label="name"49            option-group-label="region"50            auto-option-focus51            @complete="searchGrouped($event.query)"52        >53            <template #option="{ option }">54                <span style="flex: 1">{{ (option as Country).name }}</span>55                <small style="color: var(--vt-text-muted-color)">{{ (option as Country).code }}</small>56            </template>57        </AutoComplete>58    </StackPanel>59</template>

Plain strings, sizes and states

1<script setup lang="ts">2import { AutoComplete } from '@vitral/vue';3import { ref } from 'vue';4 5const words = ref<string | null>(null);6const wordSuggestions = ref<string[]>([]);7</script>8 9<template>10    <AutoComplete11        v-model="words"12        :suggestions="wordSuggestions"13        aria-label="Word"14        size="small"15        @complete="wordSuggestions = ['alpha', 'beta', 'gamma', 'delta'].filter((w) => w.includes($event.query))"16    />17    <AutoComplete :suggestions="[]" aria-label="Filled" variant="filled" />18    <AutoComplete :suggestions="[]" aria-label="Loading" loading />19    <AutoComplete :suggestions="[]" aria-label="Invalid" invalid />20    <AutoComplete :suggestions="[]" aria-label="Disabled" disabled model-value="Disabled" dropdown />21</template>

API

Read from packages/vue/src/components/AutoComplete/types.ts, so it says what the component actually accepts.

Props

Name	Type	Description
suggestions	any[]	What the list offers for the current query; the app sets it in answer to `complete`.
optionLabel	string	Field (dotted path) holding a suggestion's text. Without it, suggestions are shown as they are.
optionDisabled	string	—
optionGroupLabel	string	Turns `suggestions` into groups: this field is each group's label…
optionGroupChildren	string	…and this one its suggestions. Defaults to `items`.
dataKey	string	Compare object values by this field instead of structurally.
multiple	boolean	v-model becomes an array, shown as chips in the field.
dropdown	boolean	Adds a button that asks for the whole list.
dropdownMode	'blank' \| 'current'	What the button asks for: every suggestion (`'blank'`, the default) or those matching the current text.
forceSelection	boolean	Only a chosen suggestion may stay in the box; other text is cleared when it loses focus.
delay	number	Milliseconds to wait after typing before asking. Defaults to 300.
minLength	number	Characters to type before asking. Defaults to 1.
completeOnFocus	boolean	Ask as soon as the box takes focus.
autoOptionFocus	boolean	Put the first suggestion in focus when the list opens, so Enter takes it.
showClear	boolean	Shows a clear button while there is a value.
loading	boolean	Shows a spinner, for while the app is searching.
showEmptyMessage	boolean	Say so when nothing matches, rather than keeping the list closed. Defaults to true.
emptySearchMessage	string	—
size	Size	—
variant	InputVariant	Defaults to the plugin's `inputVariant`.
invalid	boolean	—
disabled	boolean	—
readonly	boolean	—
fluid	boolean	—
placement	OverlayPlacement	—
appendTo	string	`'body'` (the default), `'self'` to render in place, or a selector.

Plus pt, dt and unstyled from BaseProps, see pass-through and unstyled mode.

Emits

Event	Payload	Description
complete	event: AutoCompleteCompleteEvent	Asks the app for the suggestions matching `query`.
option-select	event: AutoCompleteOptionEvent	—
option-unselect	event: AutoCompleteOptionEvent	—
dropdown-click	event: AutoCompleteCompleteEvent	—
clear	—	—
show	—	—
hide	—	—
focus	event: FocusEvent	—
blur	event: FocusEvent	—

Slots

Name	Slot props	Description
option	(props: { option: unknown; index: number; selected: boolean; focused: boolean })	—
optiongroup	(props: { group: unknown })	—
chip	(props: { value: unknown; label: string; remove: (event: Event) => void })	A chip's content in multiple mode.
header	—	—
footer	—	—
empty	—	—
dropdownicon	—	—

AutoComplete

Import

API

Props

Emits

Slots

Related components