◇

Combobox

15 parts

An autocomplete / typeahead input that filters a list of options as the user types. Combine a text input with a popup listbox, supporting single or multiple selection, custom filtering, and full keyboard navigation. Reach for it when users must pick from a large or searchable set of options; for a small fixed list a plain Select is simpler. Wraps everything in a Popper and provides shared state to every other Combobox part.

Source

Demo

Loading demo…

Anatomy

Import the parts and compose them. Each part forwards attributes to its underlying element.

vue

import {
  ComboboxAnchor,
  ComboboxArrow,
  ComboboxCancel,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxInput,
  ComboboxItem,
  ComboboxItemIndicator,
  ComboboxLabel,
  ComboboxPortal,
  ComboboxRoot,
  ComboboxSeparator,
  ComboboxTrigger,
  ComboboxViewport,
} from '@robonen/primitives/selection/combobox';

<ComboboxRoot>
  <ComboboxAnchor />
  <ComboboxArrow />
  <ComboboxCancel />
  <ComboboxContent />
  <ComboboxEmpty />
  <ComboboxGroup />
  <ComboboxInput />
  <ComboboxItem />
  <ComboboxItemIndicator />
  <ComboboxLabel />
  <ComboboxPortal />
  <ComboboxSeparator />
  <ComboboxTrigger />
  <ComboboxViewport />
</ComboboxRoot>

API Reference

ComboboxAnchor

Anchor

The element the popup is positioned against, typically wrapping the Input and Trigger. Acts as the Popper anchor and the boundary used for the blur-to-close heuristic.

No props or events — renders its element and forwards attributes.

ComboboxArrow

Arrow

No props or events — renders its element and forwards attributes.

ComboboxCancel

Cancel

A button that clears the current search term and refocuses the input. Typically shown as an "x" inside the field while the user is typing.

No props or events — renders its element and forwards attributes.

ComboboxContent

Content

The popup listbox that holds the options. Mounts only while open (via Presence) and positions itself relative to the anchor. Place the Viewport, Items, and Empty inside it.

Prop	Type	Default	Description
`forceMount`?	`boolean`	`false`	Keep the content mounted even while closed (for external animation libraries).

ComboboxEmpty

Empty

Fallback content shown when the current search term matches no items. Renders only when the filtered count is zero, unless `always` is set.

Prop	Type	Default	Description
`always`?	`boolean`	—	Render even when items exist but none are filtered out.

ComboboxGroup

Group

Groups related items under a shared ComboboxLabel. Hides itself automatically when none of its items survive the current filter.

No props or events — renders its element and forwards attributes.

ComboboxInput

Input

The text field users type into to filter options. Owns the search term, ARIA combobox semantics, and keyboard navigation (arrows, Home/End, Enter to select, Escape to close).

Prop	Type	Default	Description
`disabled`?	`boolean`	—	Disable the input.
`autoFocus`?	`boolean`	—	Focus the input on mount.
`openOnFocus`?	`boolean`	—	Open the combobox when the input is focused. Combined (OR) with the Root-level `openOnFocus`.
`openOnClick`?	`boolean`	—	Open the combobox when the input is clicked. Combined (OR) with the Root-level `openOnClick`.

ComboboxItem

Item

A single selectable option in the list. Registers itself for filtering and keyboard navigation, toggles selection on click, and highlights on pointer move.

Prop	Type	Default	Description
`value`	`T`	—	Item value. Selected/registered identity.
`textValue`?	`string`	—	Optional explicit text for filter + typeahead.
`disabled`?	`boolean`	—	Disable this item.

ComboboxItemIndicator

ItemIndicator

Marks the selected state of its parent ComboboxItem, e.g. a checkmark. Renders only when that item is selected.

No props or events — renders its element and forwards attributes.

ComboboxLabel

Label

An accessible label for a ComboboxGroup. Its id is referenced by the group's `aria-labelledby`, so place it as a direct child of ComboboxGroup.

No props or events — renders its element and forwards attributes.

ComboboxPortal

Portal

Teleports the ComboboxContent into another part of the DOM (defaults to `body`) to escape overflow/stacking-context clipping. Wrap ComboboxContent with it.

No props or events — renders its element and forwards attributes.

ComboboxRoot

Root

Prop	Type	Default	Description
`modelValue`?	`T \| T[]`	—	Controlled selected value. Use `v-model`.
`defaultValue`?	`T \| T[]`	—	Uncontrolled initial value.
`defaultOpen`?	`boolean`	—	Uncontrolled default open state.
`multiple`?	`boolean`	—	Allow selecting multiple values.
`dir`?	`Direction`	—	Reading direction. Falls back to `ConfigProvider`.
`disabled`?	`boolean`	—	Disable the whole combobox.
`required`?	`boolean`	—	Mark as required for native form validation.
`name`?	`string`	—	Native input name for form submission.
`resetSearchTermOnBlur`?	`boolean`	`true`	Reset the search term when the input is blurred.
`resetSearchTermOnSelect`?	`boolean`	`true`	Reset the search term when a value is selected (single mode).
`resetModelValueOnClear`?	`boolean`	`false`	Clear the model value (to `undefined`, or `[]` when `multiple`) when the search is cleared via ComboboxCancel.
`openOnFocus`?	`boolean`	`false`	Open the combobox when the input is focused. Root-level default for every ComboboxInput; a per-input prop still overrides it.
`openOnClick`?	`boolean`	`false`	Open the combobox when the input is clicked. Root-level default for every ComboboxInput; a per-input prop still overrides it.
`highlightOnHover`?	`boolean`	`true`	Highlight items on pointer hover. Set `false` to opt out of pointermove highlighting.
`ignoreFilter`?	`boolean`	—	Skip the built-in filter; render every item regardless of search term.
`filterFunction`?	`ComboboxFilterFunction`	—	Custom filter implementation. Overrides the default substring match.
`displayValue`?	`(value: T \| T[] \| undefined) => string`	—	Map the current model value to the input's display value.
`by`?	`string \| ((a: T, b: T) => boolean)`	—	Compare values by key, or via a custom comparator.
`open`?	`boolean`	—	Two-way bound value (`v-model:open`).

Emits

Event	Payload
`update:open`	`[value: boolean]`
`update:modelValue`	`[value: T \| T[] \| undefined]`

ComboboxSeparator

Separator

A purely visual divider between items or groups inside the popup. Decorative and hidden from assistive technology.

No props or events — renders its element and forwards attributes.

ComboboxTrigger

Trigger

A button, usually a chevron next to the input, that toggles the popup open and closed. Optional: typing in the Input also opens the list.

Prop	Type	Default	Description
`disabled`?	`boolean`	—	Disable the trigger independently from the root.

ComboboxViewport

Viewport

The scrollable region inside ComboboxContent that holds the items. Provides the overflow container that keeps the highlighted item scrolled into view.

Prop	Type	Default	Description
`nonce`?	`string`	—	CSP `nonce` applied to the injected scrollbar-hiding `<style>` tag. Falls back to the `ConfigProvider` nonce when omitted.