Combobox

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

Combobox shares Select's labelClearance prop and fieldContextKey default. Preserve the surrounding layout's intended density and add clearance only when its floating label needs it. See the floating label spacing guide.

State

Props

Name	Description	Default	Control
`size`Optional	The trigger height. Matches the 32px, 40px, and 56px TextField and Button sizes. `TextFieldSize \| undefined`	-	-
`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[]`	-	-
`supportingText`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`	-
`labelClearance`Optional	CSS length reserved at block-start for the floating label. Overrides FieldContext. `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.	-
`locale`	`(() => string \| undefined) \| undefined`	No	BCP 47 locale used for locale-sensitive filtering.	-
`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`	`SelectMenuRef`	Yes	Ref to the menu exposed API.	-
`triggerRef`	`Ref<HTMLElement \| undefined, HTMLElement \| undefined>`	Yes	Ref to the trigger element.	-
`textFieldRef`	`SelectTextFieldRef`	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 ​