When should I use Combobox instead of Select?

Combobox accepts free text and filters options as the user types. Select is the non-typeahead equivalent, where the user picks from a fixed list without typing.

How do I filter options on the server instead of the client?

Pass a ServerComboboxAdapter to Combobox.Root to disable client-side filtering, then debounce the query and run your async lookup. The default ClientComboboxAdapter filters the in-memory list by substring.

Why does an item stay selected after it's filtered out of view?

Items render with v-show (not v-if) against the filtered set, so they're hidden rather than unmounted. Selection state is preserved even when an option isn't currently matched.

How do I stop users from keeping free text that doesn't match an option?

Set strict on Combobox.Root. By default, confirming with Enter, Tab, click-outside, or blur commits unmatched text as a free-text value through v-model; with strict, unmatched text is discarded on confirm and the input reverts to the selected option's value — or clears if nothing is selected — so only registered options can be chosen. Escape (and close()) still cancel.

How do I submit the selected value(s) with a native form?

Set name on Combobox.Root and it auto-renders one hidden input per selected value. Combobox doesn't export a hidden-input sub-component, so you never place one by hand.

Combobox

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

Markdown

PreviewRenders elementIntermediateNov 2, 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

Theme

Mode

Palettes

Accessibility

basic.vue

<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.Root>
</template>

Architecture

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 query reaches the fetch without prop-drilling. A renderless SearchWatcher — a defineComponent with render: () => null — reads the combobox context via useComboboxRoot 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

Theme

Mode

Palettes

Accessibility

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

aria-autocomplete="both" is set automatically when strict is enabled (versus "list" when free-text is allowed), signaling to assistive tech that the field resolves to one of the listed options.

Key	Action
`ArrowDown` / `ArrowUp`	Open dropdown, or move highlight down / up
`Enter`	Select highlighted item, or commit the typed value (unless `strict`)
`Escape`	Close dropdown and discard the typed value
`Tab`	Accept the highlighted item if one is active, otherwise commit the typed value, then close and move focus
`Home` / `End`	Move the caret in the input; list highlight is cleared

Click-outside and blur always commit() the query (ignores leftover virtual focus) then close. Tab accepts a highlight when one exists, otherwise commits. Escape / close() cancel without committing.

FAQ

Discord

Need help? Join our community for support and discussions ↗

API Reference

The following API details are for all variations of the Combobox component.

Combobox.Root

14 props, 1 event, 1 slot