Components

Combobox

An input with a list of options where the user picks one or more items from a fixed list.

Source code

Click to see the source code for this component on GitHub. Feel free to copy it and adjust it for your own use.

Installation

To use the combobox inside a Vee-Validate form, see VeeCombobox.

Hand-rolled comboboxes

Older versions of this page built the combobox by hand from UiPopover and UiCommand. That still works (see the Command docs), but UiCombobox is now built on Reka UI's Combobox primitive and handles filtering, keyboard navigation, multiple selection and form values for you.

Combobox vs. Autocomplete

	Combobox	Autocomplete
`v-model`	The selected item(s): a string, number, object or an array when `multiple`	The text in the input (`string`)
Free-form text	No, the value must be one of the items	Yes, any text is a valid value
Selecting an item	Sets the model to the item's `value`	Fills the input with the item's text
On blur	Resets the input to the selection	Keeps the typed text
`multiple` / object values	Supported	Not supported

Use a combobox when the user has to choose from a fixed list, or when you need objects or multiple selection. Use UiAutocomplete when suggestions are only a convenience.

Usage

Basic

The model holds the selected item. The input searches the list and shows the selection once the list closes.

Selected: (none)

Objects

Items can have any value, including objects. Use by to tell the combobox how to compare objects, and display-value on UiComboboxInput to control what the input shows for the selected object. Set text-value on the item so it can be searched.

Selected: nuxt.js

Groups

Use UiComboboxGroup and UiComboboxLabel to organise the items. Visible groups are divided by a line automatically, and groups that do not match the search are hidden along with their divider. Individual items can be disabled.

Multiple

Set multiple to allow more than one item. The model becomes an array. Reka UI recommends rendering the selection as tags: wrap a UiTagsInput in UiComboboxAnchor (with as-child) and render the input with UiTagsInputInput.

TypeScript

Rust

Selected: 2

Clearable

Use UiComboboxCancel to render a button that clears the search. Add reset-model-value-on-clear to also reset the model to null (or [] when multiple).

Custom item content

Items accept any content, such as icons, avatars or descriptions. Content that is not plain text needs text-value so the item can still be searched. Here the selected item also drives an icon placed before the input.

Open on focus or click

By default the list opens once the user starts typing or presses the arrow keys. Use open-on-focus or open-on-click to open it as soon as the input is focused or clicked.

Open on focus

Open on click

Async

Fetch items from your API as the user types. Use ignore-filter so the results returned from the server are not filtered a second time on the client, and listen to update:modelValue on UiComboboxInput to get the search term. The selected object is kept in the model, so its label survives while the list of results changes.

Selected: (none)

Form

Pass a name to include the selected value when the surrounding <form> is submitted. For validation, see VeeCombobox.

Disabled

Set disabled on the root to prevent interaction, or on individual items.

Disabled combobox

Disabled items

Props

Combobox

Prop	Type	Default	Description
`v-model`	`T \| T[]`		The selected item. An array when `multiple`.
`default-value`	`T \| T[]`		Initial selection when uncontrolled.
`multiple`	`boolean`	`false`	Allow selecting more than one item.
`by`	`string \| ((a: T, b: T) => boolean)`		Property name or comparator used to compare object values.
`v-model:open`	`boolean`		Controls whether the list is open.
`default-open`	`boolean`		Initial open state when uncontrolled.
`open-on-focus`	`boolean`	`false`	Open the list when the input is focused.
`open-on-click`	`boolean`	`false`	Open the list when the input is clicked.
`ignore-filter`	`boolean`	`false`	Disable the built-in filtering. Use it when you filter the items yourself, for example with data from an API.
`reset-search-term-on-blur`	`boolean`	`true`	Reset the search term when the input loses focus.
`reset-search-term-on-select`	`boolean`	`true`	Reset the search term when an item is selected.
`reset-model-value-on-clear`	`boolean`	`false`	Reset the model when `UiComboboxCancel` is used.
`highlight-on-hover`	`boolean`	`true`	Highlight items on hover.
`name`	`string`		Name used when the combobox is part of a native form.
`required`	`boolean`		Marks the field as required.
`disabled`	`boolean`		Prevents interaction.
`dir`	`"ltr" \| "rtl"`		Reading direction.

The root emits update:modelValue, update:open and highlight.

ComboboxInput

Prop	Type	Description
`display-value`	`(value: T) => string`	What the input shows for the selected item once the list is closed. Needed for object values. Not used with `multiple`.

Emits update:modelValue with the text in the input as the user types.

ComboboxContent

Accepts all of the Reka UI popper content props. The ones used most often are:

Prop	Type	Default	Description
`hide-when-empty`	`boolean`	`false`	Hide the popup while no item matches.
`side`	`"top" \| "right" \| "bottom" \| "left"`	`"bottom"`	Preferred side of the input.
`side-offset`	`number`	`8`	Distance in pixels from the input.
`position`	`"inline" \| "popper"`	`"popper"`	Positioning strategy.

ComboboxItem

Prop	Type	Description
`value`	`T`	The value stored in the model when the item is selected.
`text-value`	`string`	Plain text used to search the item. Needed when the content is not plain text.
`disabled`	`boolean`	Prevents the item from being selected.
`icon`	`string`	Icon shown when the item is selected. Defaults to `lucide:check`.

Accessibility

The input has the combobox role and the items are exposed as a listbox. Focus stays in the input while you move through the items.

Key	Description
`ArrowDown` / `ArrowUp`	Opens the list, then moves the highlight.
`Enter`	Selects the highlighted item.
`Esc`	Closes the list and keeps focus in the input.
`Tab`	Moves focus away. The input resets to the current selection.

Color Picker

A fully-featured color picker component with support for multiple color formats, alpha channel, and preset swatches.

Command

A command menu component composed of the Combobox primitives from Reka UI.