Combobox

Combobox combines free-form text entry with option picking, making it useful for searchable single- and multi-select flows.

State

Props

Name	Description	Default	Control
`disabled`Optional	Whether the control is disabled. `boolean \| undefined`	-
`name`Optional	Name used for hidden inputs during form submission. `string \| undefined`	-
`multiple`Optional	Enables multi-select behavior. `boolean \| undefined`	-	-
`label`Optional	Visible label. If omitted, provide aria-label via attrs. `string \| undefined`	-
`id`Optional	Optional explicit id for the trigger element. `string \| undefined`	-
`options`Required	Selectable options rendered in the menu. `SelectOption[]`	-	-
`description`Optional	Supporting text shown below the field when not in error state. `string \| undefined`	-
`error`Optional	Error text shown below the field. When provided, field is invalid. `string \| undefined`	-
`required`Optional	Whether the control is required. `boolean \| undefined`	-
`placeholder`Optional	Placeholder shown when nothing is selected. `string \| undefined`	-
`clearable`Optional	Shows a trailing button that clears the current selection. `boolean \| undefined`	-
`clearLabel`Optional	Accessible label for the clear button. `string \| undefined`	-
`menuColor`Optional	Visual color style of the dropdown menu. `MenuColor \| undefined`	-	-
`displaySeparator`Optional	Separator used when showing multiple selected labels. `string \| undefined`	-
`filterPlaceholder`Optional	Placeholder shown in the menu filter field. `string \| undefined`	-
`filterNoResultsText`Optional	Message shown when filtering returns no matching options. `string \| undefined`	-
`modelValue`Optional	- `SelectModelValue`	-	-
`open`Optional	- `boolean \| undefined`	`false`

Events5

Name	Type	Description
`update:open`	`[value: boolean]`	-
`update:modelValue`	`[value: SelectModelValue]`	-
`change`	`[value: SelectModelValue]`	-
`focus`	`[event: FocusEvent]`	-
`blur`	`[event: FocusEvent]`	-

Slots6

Name	Parameters	Description
`leading`	-	-
`prefix`	-	-
`suffix`	-	-
`trailing`	-	-
`optionLeading`	-	-
`optionTrailing`	-	-

INFO

Combobox 是 Select 的封装，共享 select scope。详见 Select Anatomy。

Examples

Default

State

Multiple Selection

States

Composable

Combobox shares the same composable as Select.

useSelect

function useSelect(opts: UseSelectOptions): UseSelectReturn

Source: src/composables/useSelect.ts

Field	Type	Required	Description	Default
`options`	`() => UseSelectOption[]`	Yes	The selectable options.	-
`multiple`	`() => boolean`	Yes	Whether multi-select is enabled.	-
`filterable`	`() => boolean`	Yes	Whether filtering is enabled.	-
`disabled`	`() => boolean`	Yes	Whether the control is disabled.	-
`displaySeparator`	`() => string`	Yes	Separator for display text in multi-select mode.	-
`modelValue`	`Ref<UseSelectModelValue, UseSelectModelValue>`	Yes	Model value ref (external).	-
`open`	`Ref<boolean, boolean>`	Yes	Open state ref (external).	-
`onChange`	`((value: UseSelectModelValue) => void) \| undefined`	No	Called when value changes.	-
`menuRef`	`Ref<{ show: (focusFirst?: boolean, source?: HTMLElement) => Promise<void>; hide: () => void; toggle: () => void; menuRef?: HTMLElement; } \| undefined, { show: (focusFirst?: boolean, source?: HTMLElement) => Promise<void>; hide: () => void; toggle: () => void; menuRef?: HTMLElement; } \| undefined>`	Yes	Ref to the menu exposed API.	-
`triggerRef`	`Ref<HTMLElement \| undefined, HTMLElement \| undefined>`	Yes	Ref to the trigger element.	-
`textFieldRef`	`Ref<{ focus: () => void; blur: () => void; } \| undefined, { focus: () => void; blur: () => void; } \| undefined>`	Yes	Ref to the text field exposed API.	-

Field	Type	Required	Description	Default
`filterQuery`	`Ref<string, string>`	Yes	Current filter query string.	-
`selectedOptions`	`ComputedRef<UseSelectOption[]>`	Yes	Options selected based on current model value.	-
`hasValue`	`ComputedRef<boolean>`	Yes	Whether any value is selected.	-
`displayText`	`ComputedRef<string>`	Yes	Display text for the current selection.	-
`submittedValues`	`ComputedRef<string[]>`	Yes	Values to submit in hidden form inputs.	-
`filteredOptionEntries`	`ComputedRef<{ option: UseSelectOption; index: number; }[]>`	Yes	Filtered option entries with original indices.	-
`hasFilteredOptions`	`ComputedRef<boolean>`	Yes	Whether there are any filtered options.	-
`isOptionSelected`	`(option: UseSelectOption) => boolean`	Yes	Check if an option is currently selected.	-
`toggleOption`	`(option: UseSelectOption) => void`	Yes	Toggle an option in the selection.	-
`clearValue`	`() => void`	Yes	Clear the current selection.	-
`handleMenuSelect`	`(event: MouseEvent, itemElement: HTMLElement) => void`	Yes	Handle menu item selection event.	-
`focus`	`() => void`	Yes	Focus the text field.	-
`blur`	`() => void`	Yes	Blur the text field.	-
`show`	`() => Promise<void>`	Yes	Show the menu.	-
`hide`	`() => void`	Yes	Hide the menu.	-
`toggle`	`() => void`	Yes	Toggle the menu.	-
`openMenu`	`(focus?: "first" \| "last") => void`	Yes	Open menu with optional focus target.	-
`closeMenu`	`() => void`	Yes	Close the menu.	-
`handleFieldClick`	`() => void`	Yes	Handle click on the trigger field.	-
`handleFieldInput`	`() => void`	Yes	Handle input on the filter field.	-
`handleFilterKeydown`	`(event: KeyboardEvent) => void`	Yes	Handle keydown on the filter field.	-

Combobox ​

Props

Events5

Slots6

Examples ​

Default ​

Multiple Selection ​