Switch

Used for toggling between two opposing states, such as "On/Off".

Basic Usage

Bind v-model to a Boolean variable.

Basic Usage

Size

Use the size property to set the dimensions of the Switch.

Size

Text Description

Use the active-text and inactive-text properties to set textual labels. Use inline-prompt to display the text inside the sliding handle area.

Text Description

Custom Icons

Use the active-icon and inactive-icon properties to add icons. Use inline-prompt to place icons inside the sliding handle area.

Custom Icons

Extended Value Types

You can set active-value and inactive-value properties, which accept Boolean, String, or Number types.

Extended Value Types

Disabled State

Set the disabled property to true to disable interaction.

Disabled State

Loading State

Set the loading property to true to display a loading spinner.

Loading State

Prevent Toggling

Use the before-change property. If it returns false or a Promise that rejects, the switch state will not change.

Prevent Toggling

Custom Action Icons

Use active-action-icon and inactive-action-icon to customize the icons inside the sliding handle (action point).

Custom Action Icons

Usage in Nuxt

The Switch component fully supports Nuxt 3/4 SSR. When used in a Nuxt project, it is auto-imported.

Usage in Nuxt

SSR Considerations:

• ✅ Basic switch state and sizing styles are fully supported.
• ✅ Text descriptions and icons render consistently during SSR.
• ✅ Extended Value types (active-value) are supported.
• ⚠️ Initial state remains consistent with client-side hydration after SSR.

SSR Safety

The Switch component is deeply optimized for SSR, ensuring that handle positions and colors are correctly calculated during server-side rendering for a fluid visual experience.

API

Props

Name	Description	Type	Default
model-value / v-model	Binding value; must equal active-value or inactive-value.	boolean | string | number	false
disabled	Whether to disable the switch	boolean	false
loading	Whether to show loading state	boolean	false
size	Switch size	'large' | 'default' | 'small'	'default'
width	Switch total width	number | string	—
inline-prompt	Whether to show icons/text inside the handle (max 3 chars)	boolean	false
active-icon	Icon displayed when status is ON (ignores active-text)	string | Component	—
inactive-icon	Icon displayed when status is OFF (ignores inactive-text)	string | Component	—
active-action-icon	Icon displayed inside the sliding handle when ON	string | Component	—
inactive-action-icon	Icon displayed inside the sliding handle when OFF	string | Component	—
active-text	Text displayed when switch is ON	string	—
inactive-text	Text displayed when switch is OFF	string	—
active-value	Value when status is ON	boolean | string | number	true
inactive-value	Value when status is OFF	boolean | string | number	false
name	Form name attribute	string	—
validate-event	Whether to trigger form validation on change	boolean	true
before-change	Hook before toggle; returning false or rejecting stops toggle	() => Promise<boolean> | boolean	—
id	Input ID	string	—
tabindex	Input tabindex	string | number	—
aria-label	Native input aria-label equivalent	string	—

Events

Name	Description	Parameters
change	Callback function when switch state changes	(value: boolean | string | number) => void

Slots

Name	Description
active-action	Custom content for the sliding handle (Action) when ON
inactive-action	Custom content for the sliding handle (Action) when OFF
active	Custom content when ON (inside handle if inline-prompt, else right side)
inactive	Custom content when OFF (inside handle if inline-prompt, else left side)

Expose

Name	Description	Type
focus	Focus the Switch	() => void
checked	Whether the Switch is currently active	ComputedRef<boolean>

Theme Variables

Variable	Description	Default
--yh-switch-on-color	Background color when active	var(--yh-color-primary)
--yh-switch-off-color	Background color when inactive	var(--yh-border-color)
--yh-switch-width	Total switch width	40px
--yh-switch-height	Total switch height	20px
--yh-switch-button-size	Sliding handle size	16px
--yh-switch-font-size	Font size	var(--yh-font-size-base)

Type Exports

Name	Description
YhSwitchProps	Component props type
YhSwitchEmits	Component emits type
YhSwitchSlots	Component slots type
YhSwitchExpose	Component expose type
YhSwitchInstance	Component instance type