Combobox

Examples

Basic

Country

Prop	Type	Default
`options` Options to choose from.	`SelectOption<T>[]`	`[]`
`label` Visible label, linked to the input.	`string`	—
`hint` Help text under the control, announced as its description.	`string`	—
`error` `true` marks the control invalid; a string also shows it as the message, replacing the hint.	`string \| boolean`	—
`placeholder` Input placeholder.	`string`	—
`multiple` Pick several; `v-model` becomes an array, shown as chips. Backspace removes the last one.	`boolean`	`false`
`creatable` Enter on text matching no option emits `create` with it.	`boolean`	`false`
`optional` Appends the `optional` translation to the label.	`boolean`	`false`
`disabled` Disables the control.	`boolean`	`false`
`filter` Custom match for each option against the lower-cased query. By default, labels are ranked exact, then prefix, then substring.	`ComboboxFilter<T>`	—
`ignoreFilter` Show `options` as given, without filtering, e.g. results from a search request.	`boolean`	`false`
`loading` Options are being fetched: shows the `loading` translation and marks the list busy.	`boolean`	`false`
`name` Form field name: submits the value with a native form, via hidden inputs.	`string`	—
`id` Id for the input; generated with `useId()` when omitted.	`string`	—
`modelValue` The selected value, or values with `multiple`.	`T \| T[]`	—
`query` The input's text. Bind it to fetch options as the user types.	`string`	`""`

Event	Payload
`create` Enter was pressed on text matching no option (with `creatable`).	`[query: string]`
`update:modelValue` `v-model:modelValue` update.	`[value: T \| T[] \| undefined]`
`update:query` `v-model:query` update.	`[value: string]`

Slot	Props
`option` Option content.	`{ option: SelectOption<T>; selected: boolean; active: boolean; }`
`chip` Each selected value in `multiple` mode. Call `remove` to deselect it.	`{ option: SelectOption<T>; remove: () => void; }`
`empty` Shown when nothing matches.	`{ query: string; }`
`create` Shown with `creatable` when Enter would create the typed value.	`{ query: string; }`
`loading` Shown while `loading`.	—

Types

export interface SelectOption<T extends SelectValue = SelectValue> {
  label: string;
  value: T;
  disabled?: boolean;
}

export type ComboboxFilter<T extends SelectValue> = (
  option: SelectOption<T>,
  query: string,
) => boolean;

export type SelectValue = string | number;

Styling

Parts: fieldfield-labelfield-optionalcombobox-controlcombobox-chipcombobox-chip-labelcombobox-chip-removecombobox-inputcombobox-popupcombobox-listboxcombobox-optioncombobox-option-labelcombobox-loadingcombobox-createcombobox-emptycombobox-statusfield-message
States: data-field-errordata-field-namedata-combobox-opendata-combobox-disableddata-combobox-activedata-field-tone

Keyboard

Keys	Action
Typing	Filter, and open the list
`↓` / `↑`	Move between options, wrapping
`Alt` + `↓`	Open without moving
`Enter`	Select the active option, or create (with `creatable`)
`Escape`	Close; press again to clear
`Backspace`	With `multiple` and an empty input, remove the last chip

Accessibility

Focus stays in the input; screen readers follow the highlighted option through aria-activedescendant.
While typing, a hidden status announces the number of matches, “No results”, or “Loading…”.
Chips aren't in the tab order, so with multiple the picks are read as part of the input's description.
In single mode, leaving the input with unmatched text restores the selection.

Examples

Basic

Tags

Async options

API

Styling

Keyboard

Accessibility