Autocomplete

Address- and search-style Autocomplete: a thin Combobox preset with free text, open-on-focus, and recent history. AutocompleteInput, AutocompleteContent, AutocompleteItem, AutocompleteEmpty, and AutocompleteLoading are the Combobox parts under preset names.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/ui

Add the public import below to <script setup lang="ts">. Components provide behavior without styles; the preview uses optional Paper styles.

import { AutocompleteContent, AutocompleteItem, AutocompleteInput, AutocompleteEmpty, AutocompleteLoading, Autocomplete, AutocompleteRoot } from "@vizejs/ui/autocomplete";

Or copy the source into your project with vize lib pull autocomplete (see Source Distribution).

Try it

This is the basic example maintained with the component source, using the public package imports. The preview adds the optional Paper styles.

Open the interactive example · Styling these components

Copy the example

<!-- Search box that suggests matching cities and remembers recent choices while the query is empty. -->
<script setup lang="ts">
import { ref, useId } from "vue";

import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteItem,
} from "@vizejs/ui/autocomplete";

const cities = ["Amsterdam", "Barcelona", "Lisbon", "Osaka", "Tokyo", "Toronto"];
const city = ref<string | null>(null);
const recent = ref<readonly string[]>(["Lisbon"]);
const labelId = useId();
</script>

<template>
  <div>
    <span :id="labelId">Destination</span>
    <Autocomplete
      v-slot="{ suggestions, showingHistory, clearHistory }"
      v-model="city"
      v-model:history="recent"
      :items="cities"
      name="destination"
    >
      <AutocompleteInput :aria-labelledby="labelId" placeholder="Search cities" />
      <AutocompleteContent>
        <AutocompleteItem v-for="entry in suggestions" :key="entry" :value="entry">
          {{ entry }}
        </AutocompleteItem>
        <AutocompleteEmpty>No matching cities</AutocompleteEmpty>
        <button v-if="showingHistory" type="button" @click="clearHistory">Clear recent</button>
      </AutocompleteContent>
    </Autocomplete>
    <output>Destination: {{ city ?? "none" }}</output>
  </div>
</template>

API

AutocompleteContent

Source: src/families/selection/select/select-content.vue

Props

Events

Slots

Exposed

AutocompleteItem<T>

Source: src/families/selection/select/select-item.vue

Props

Slots

Exposed

AutocompleteInput

Source: src/families/selection/combobox/combobox-input.vue

Props

Exposed

AutocompleteEmpty

Source: src/families/selection/combobox/combobox-empty.vue

Slots

AutocompleteLoading

Source: src/families/selection/combobox/combobox-loading.vue

Slots

Autocomplete<T>

Source: src/families/selection/autocomplete/autocomplete-root.vue

Props

Events

Slots

Exposed

AutocompleteRoot<T>

Source: src/families/selection/autocomplete/autocomplete-root.vue

Props

Events

Slots

Exposed

Behavior

Contract

Autocomplete is a thin, typed preset over Combobox for address- and search-style inputs. autocomplete-root.vue wraps ComboboxRoot with free text (strict: false), list autocompletion, open-on-focus, and a recent-history list that is shown while the query is empty. History is controllable (v-model:history), de-duplicated under by, capped by maxHistory, and can persist through an injectable historyStorage adapter that is read only after mount; slot state exposes forget and clearHistory. All Combobox parts (input, content, items, async loading, virtualization) apply.

Normative Behavior

SSR

History is rendered from defaultHistory on the server; storage is read only after mount, so markup is byte-identical and hydrates without warnings (renders byte-identical Autocomplete markup with history suggestions, hydrates Autocomplete without mismatches or node replacement).