Props

Name	Type	Default	Description
label	string	-	Field label. It also names the popup.
modelValue	Value	-	Current value. Bind with v-model.
triggerLabel	string	-	Text on the trigger. Falls back to placeholder.
placeholder	string	Select…	Shown when triggerLabel is empty.
isLabelHidden	boolean	false	Hide the visible label. The accessible name stays.
description	string	-	Supporting text under the label.
isOptional	boolean	false	Marks the field optional.
isRequired	boolean	false	Marks the field required.
isDisabled	boolean	false	The trigger does not open.
isLoading	boolean	false	Shows a spinner on the trigger.
status	FieldStatusInput	-	Error, warning, or success message.
statusVariant	'attached' | 'detached' | 'tooltip'	'attached'	Where the status message sits.
labelTooltip	string	-	Tooltip on the label.
size	'sm' | 'md' | 'lg'	'md'	Trigger size.
width	number | string	-	Field width. Numbers are pixels.
placement	PopoverPlacement	'below'	Where the popup opens.
alignment	'start' | 'center' | 'end'	'start'	Popup alignment along the placement axis.
startIcon	string | Component	-	Icon at the start of the built-in trigger.
variant	'input' | 'secondary' | 'ghost'	'input'	input is the bordered field. secondary matches a secondary button. ghost matches a toolbar button. On the latter two, an attached status becomes detached.
containerClass / controlClass	class	—	The shell takes container* and the root class. The built-in button takes control*. A custom trigger ignores both and warns in development.
renderTrigger	(props) => VNode	-	Replaces the field and the built-in trigger. Spread props onto your control. The trigger slot does the same job.
handleRef	Ref | (handle) => void	-	Receives open, close, toggle, and isOpen. A template ref exposes the same methods.
changeAction	(value) => void | Promise<void>	-	Runs after the value changes. While it is pending the trigger shows a spinner.

Events

Name	Payload	Description
update:modelValue	Value	The value passed to commit.
change	Value	Emitted with update:modelValue.
click	event: MouseEvent	Emitted for a click on the trigger, before the popup opens. Call event.preventDefault() to keep it closed. With the trigger slot or renderTrigger it runs after the toggle and cannot cancel it.
keydown	event: KeyboardEvent	Emitted for keys on the trigger after the built-in handling, and receives every key, including the ArrowDown that opens the popup. With a custom trigger, keys the built-in handling cancels are not emitted.
openChange	isOpen: boolean	Emitted whenever the surface opens or closes, however it happened: trigger, keyboard, light dismiss, Escape, close(), or the imperative handle.

Slot

The default slot receives value, commit, close, and state. state is { isOpen, isBusy, triggerId, contentId }. value includes a pending optimistic value.