Switch Props

Name	Type	Default	Description
v-model	boolean	—	Required. Current switch state.
label	string	—	Required. Accessible name of the control.
id	string	—	ID of the native input. Auto-generated when omitted.
size	'sm' | 'md' | 'lg'	'md'	Switch size.
width	number | string	—	Component width. Numbers are treated as px.
description	string	—	Description shown below the label.
isLabelHidden	boolean	false	Hide the visual label while keeping the accessible name.
isDisabled	boolean	false	Prevent changes.
disabledMessage	string	—	Reason for disabling. The control stays focusable when this is provided.
isReadOnly	boolean	false	Prevent changes. The value is still submitted.
isLoading	boolean	false	Show loading state and block repeated toggles.
loadingLabel	string	'Loading'	Accessible text for the loading state.
isRequired	boolean	false	Show required indicator and enable native required validation.
isOptional	boolean	false	Show optional indicator. Takes precedence over isRequired.
optionalLabel	string	'Optional'	Text for the optional indicator.
requiredLabel	string	'Required'	Text for the required indicator.
htmlName	string	—	Form field name. Takes precedence over native name.
form	string	—	ID of the associated form.
status	FieldStatusInput	—	Status type, message, and message ID.
statusVariant	'attached' | 'detached' | 'tooltip'	'detached'	Where to display the status message.
changeAction	SwitchChangeAction	—	Action run after toggling. Supports Promise.
hasAutoFocus	boolean	false	Focus the input after mount.
labelIcon	Component	—	Decorative icon before the label.
labelTooltip	string	—	Tooltip shown next to the label.

Status

status has these fields:

• type: 'error', 'warning', or 'success'.
• message: message text.
• messageId: message ID.

The default statusVariant is detached, so the message appears below the switch.

Events

• update:modelValue(value): emitted after the user toggles.
• change(value, event): fired after the model updates.
• actionError(error, value, event): emitted when the async action rejects or throws.

event is a cancellable SwitchChangeEvent. event.detail.originalEvent keeps the native event. Calling event.preventDefault() inside change skips changeAction. It does not roll back the model update.

Async action

changeAction(value, event) receives the new value and the component event.

• The component shows a loading state while the Promise is pending.
• Repeated toggles are blocked until the Promise settles.
• The parent-bound value takes precedence over any temporary display value.
• The component clears the loading state after success or failure.
• Failed actions do not roll back the value written to v-model.
• Use @action-error to display failures.
• Roll back in application code when needed.

Slots

• labelIcon: decorative icon before the label. Overrides the labelIcon prop.

Template ref

• element: HTMLInputElement | null.
• focus(options?: FocusOptions): focus the input.
• blur(): remove focus from the input.

Native attributes

class and style are applied to the outer wrapper. Unrecognized native attributes and listeners are forwarded to the input. The component manages checked, type, role, and core ARIA states.