MultiSelector Props

Name	Type	Default	Description
modelValue	(string | number)[]	[]	Selected values.
options	MultiSelectorOption[]	Required	Strings, option objects, dividers, or sections.
label	string	Required	Field label.
isLabelHidden	boolean	false	Hides the label visually while keeping it accessible. labelHidden is the older name; either one hides it.
placeholder	string	Select… / 请选择	Placeholder when nothing is selected.
searchable	boolean	false	Show a search field in the menu.
selectAll	boolean	false	Show a select-all row. Disabled options are skipped.
triggerDisplay	'count' | 'labels' | 'badges'	'count'	How the closed trigger shows the selection.
maxBadges	number	3	How many badges or labels stay visible before +N. Width can collapse them further.
clearable	boolean	false	Show a clear button.
hasClear	boolean	false	Shows a clear button when values are selected. clearable is the older name; either one turns it on.
checkboxPosition	'start' | 'end'	'start'	Where the check mark sits.
variant	'input' | 'secondary' | 'ghost'	'input'	input has a border. secondary matches a secondary button. ghost fits a toolbar. On the latter two, an attached status becomes detached.
containerClass / controlClass	class	—	Shell and trigger box. A root class lands on the box. An option action latches a two-column grid and does not change the selection.
disabled	boolean	false	Disable the field.
disabledMessage	string	—	Why the field is disabled. With disabled, hovering or keyboard focus shows a tooltip and the trigger stays focusable through aria-disabled; it still cannot open the list. Do not wrap a disabled selector in a tooltip: it would swallow the hover. disabledReason is the older name.
disabledReason	string	—	Reason for the disabled state. The control stays focusable. Same as disabledMessage.
isDefaultOpen	boolean	false	Starts with the list open on mount.
status	'default' | 'success' | 'warning' | 'error'	'default'	Status style.
statusMessage	string	—	Status text under the field.
statusVariant	'attached' | 'detached' | 'tooltip'	'attached'	Where the status message sits. Ghost detaches an attached message. Tooltip keeps it on the icon inside the field.
size	'sm' | 'md' | 'lg'	'md'	Size.
name	string	—	Form field name. Each selected value is submitted once.
isReadOnly	boolean	false	Read-only. The selection stays, can be focused and submitted, and cannot be opened or cleared. It does not dim.
isLoading	boolean	false	Shows a spinner in the trigger. The create row and the empty state stay hidden.
formatValue	(items) => string	—	Custom closed text. Used by count and labels only. Badges ignore it. An empty selection does not call it.
hasCreate	boolean	false	Use with search. When the text matches no label, ignoring case, the first row creates it.
handleRef	Ref | (handle) => void	—	Open, close, or ask whether the menu is open. Pass a function from a template. Open does nothing when read-only or disabled.
emptyText	string	No matches / 无匹配项	Shown when the list itself has no options.
emptySearchText	string	No results found / 未找到结果	Shown when a search matches nothing.

MultiSelector Emits

Name	Parameters	Description
update:modelValue	value: (string | number)[]	Emitted when the selection changes.
change	value, change?	Emitted when the selection changes. A create also passes { type: 'create', query }.
search	query: string	Emitted when the search text changes.
openChange	isOpen: boolean	Emitted when the menu opens or closes.
click	event: MouseEvent	Emitted for a click on the trigger, after the menu toggles. It cannot cancel the toggle.
focus	event: FocusEvent	Emitted when the trigger takes focus.
keydown	event: KeyboardEvent	Emitted for keys on the trigger that the built-in keyboard model leaves alone. Keys it handles and cancels are not emitted.

MultiSelector Slots

Name	Parameters	Description
icon	—	Icon at the start of the trigger.
option	{ option, selected, active }	Custom option.
empty	—	Custom empty state.
trigger	{ id, onClick, onKeyDown, onFocus, aria-haspopup, aria-expanded, aria-controls, aria-busy, triggerRef }	Replaces the whole field and trigger with your own control (a glyph in a row, a chip, an icon button). Spread the bindings onto it and pass triggerRef as :ref so the list anchors to it. The field chrome (label, status, clear, spinner) is not rendered.