Combobox

A headless autocomplete input that filters options as the user types, with client and server-side filtering support.

Copy Markdown

PreviewRenders elementIntermediate Jun 29, 2026

Usage

The Combobox component follows the same compound pattern as Select, but replaces the activator button with a Control input that accepts free text. Filtering happens automatically as the user types.

Selected: None

<script setup lang="ts">
  import { Combobox } from '@vuetify/v0'
  import { shallowRef } from 'vue'

  const selected = shallowRef<string>()

  const fruits = [
    { id: 'apple', label: 'Apple' },
    { id: 'banana', label: 'Banana' },
    { id: 'cherry', label: 'Cherry' },
    { id: 'date', label: 'Date' },
    { id: 'elderberry', label: 'Elderberry' },
    { id: 'fig', label: 'Fig' },
    { id: 'grape', label: 'Grape' },
  ]
</script>

<template>
  <div class="flex flex-col gap-4 max-w-xs mx-auto">
    <Combobox.Root v-model="selected">
      <Combobox.Activator class="flex items-center gap-1 w-full px-3 py-2 rounded-lg border border-divider bg-surface text-on-surface text-sm">
        <Combobox.Control
          class="flex-1 bg-transparent outline-none text-on-surface placeholder:text-on-surface-variant"
          placeholder="Search fruits…"
        />

        <Combobox.Cue class="opacity-50 cursor-pointer transition-transform data-[state=open]:rotate-180"><svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path d="M5 9l7 7 7-7" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" /></svg></Combobox.Cue>
      </Combobox.Activator>

      <Combobox.Content class="p-1 rounded-lg border border-divider bg-surface shadow-lg" :style="{ minWidth: 'anchor-size(width)' }">
        <Combobox.Item
          v-for="item in fruits"
          :id="item.id"
          :key="item.id"
          class="px-3 py-2 rounded-md cursor-default select-none text-sm text-on-surface data-[selected]:text-primary data-[selected]:font-medium data-[highlighted]:bg-primary data-[highlighted]:text-on-primary data-[highlighted]:data-[selected]:text-on-primary"
          :value="item.label"
        >
          {{ item.label }}
        </Combobox.Item>

        <Combobox.Empty v-slot="{ query }" class="px-3 py-2 text-sm text-on-surface-variant">
          No results for "{{ query }}"
        </Combobox.Empty>
      </Combobox.Content>
    </Combobox.Root>

    <p class="text-sm text-on-surface-variant">
      Selected: {{ selected ?? 'None' }}
    </p>
  </div>
</template>

Anatomy

vue

<script setup lang="ts">
  import { Combobox } from '@vuetify/v0'
</script>

<template>
  <Combobox.Root>
    <Combobox.Activator>
      <Combobox.Control />

      <Combobox.Cue />
    </Combobox.Activator>

    <Combobox.Description />

    <Combobox.Error />

    <Combobox.Content>
      <Combobox.Item />

      <Combobox.Empty />
    </Combobox.Content>

    <Combobox.HiddenInput />
  </Combobox.Root>
</template>

Root creates selection, virtual focus, popover, and adapter contexts. Control drives the query string — the adapter translates queries into a filtered ID set. Items register with selection and use v-show (not v-if) against the filtered set, preserving selection state even when hidden. Empty renders when the filtered set is empty. Description and Error provide accessible help text and validation messages linked to Control via ARIA attributes.

Examples

Async assignee picker

A GitHub-style assignee picker that searches people from a mocked server as you type. It wires ServerComboboxAdapter onto Combobox.Root to disable client-side filtering, debounces the query, runs an async lookup that resolves a Promise, shows a loading hint while the request is in flight, and renders multi-select chips for everyone assigned. When the server returns nothing, Combobox.Empty reports the unmatched term.

The interesting piece is how the query reaches the fetch without prop-drilling. A renderless SearchWatcher — a defineComponent with render: () => null — reads the combobox context via useComboboxContext and watches its query, emitting a search event that the composable debounces before calling the mock search(). Results flow back down as a prop, so Combobox.Item re-registers on each update. open-on="input" on Combobox.Control keeps an empty focus from firing a needless fetch, and the name prop on Combobox.Root auto-renders the hidden inputs for native form submission — one per selected handle — so you never place a hidden input by hand (Combobox does not export one).

Reach for this whenever the dataset is too large to ship to the client, needs full-text indexing, or depends on server context like permissions or org membership. The trade-off versus the default ClientComboboxAdapter is the debounce-and-network latency and the loading state you must surface; for small static lists, prefer client filtering. Related: createSelection powers the multi-select state, and Select covers the non-typeahead equivalent.

File	Role
`useUserSearch.ts`	Owns the mock user dataset, debounced `onSearch`, async `search` returning a Promise, loading flag, and assignee state
`UserPicker.vue`	Reusable combobox surface — server adapter, SearchWatcher, chips, results list, and Empty state; owns the UnoCSS classes
`user-picker.vue`	Demo entry wiring the composable to the picker, with an assignment summary and a clear action

Results are fetched from a mock server as you type.

No one assigned yet

Recipes

Form Submission

Set name on Root to auto-render hidden inputs for form submission — one per selected value in multi-select mode:

vue

<template>
  <Combobox.Root v-model="value" name="country">
    <!-- ... -->
  </Combobox.Root>
</template>

Custom Client Filtering

Pass a ClientComboboxAdapter with a custom filter function to override the default substring matching:

vue

<script setup lang="ts">
  import { Combobox, ClientComboboxAdapter } from '@vuetify/v0'

  const adapter = new ClientComboboxAdapter({
    filter: (query, value) => String(value).toLowerCase().startsWith(query.toLowerCase()),
  })
</script>

<template>
  <Combobox.Root :adapter>
    <!-- ... -->
  </Combobox.Root>
</template>

Open on Input Only

By default the dropdown opens on focus. Set open-on="input" on Control to only open when the user starts typing — useful for server search where an empty query should not trigger a fetch:

vue

<template>
  <Combobox.Control open-on="input" placeholder="Type to search…" />
</template>

Data Attributes

Style interactive states without slot props:

Attribute	Values	Component
`data-selected`	`true`	Item
`data-highlighted`	`""`	Item
`data-disabled`	`true`	Item
`data-state`	`"open"` / `"closed"`	Activator, Cue

Accessibility

The Combobox implements the WAI-ARIA Combobox↗︎ pattern with a listbox popup.

ARIA Attributes

Attribute	Value	Component
`role`	`combobox`	Control
`role`	`listbox`	Content
`role`	`option`	Item
`aria-autocomplete`	`list` / `both`	Control
`aria-expanded`	`true` / `false`	Control
`aria-haspopup`	`listbox`	Control
`aria-controls`	listbox ID	Control
`aria-activedescendant`	highlighted option ID	Control
`aria-describedby`	description ID	Control (when Description mounted)
`aria-errormessage`	error ID	Control (when Error mounted and errors exist)
`aria-invalid`	`true`	Control (when invalid)
`aria-selected`	`true` / `false`	Item
`aria-disabled`	`true`	Item (when disabled)
`aria-multiselectable`	`true`	Content (when multiple)
`aria-hidden`	`true`	Cue
`aria-live`	`polite`	Error

Tip

aria-autocomplete="both" is set automatically when strict is enabled, signaling that the input value will revert to a valid option on close.

Key	Action
`ArrowDown` / `ArrowUp`	Open dropdown, or move highlight down / up
`Enter`	Select highlighted item
`Escape`	Close dropdown
`Tab`	Close dropdown and move focus
`Home`	Move highlight to first item
`End`	Move highlight to last item