Skip to content
Latestv1.0.63

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 ​

NameDescriptionTypeDefault
model-value / v-modelBinding value; must equal active-value or inactive-value.boolean | string | numberfalse
disabledWhether to disable the switchbooleanfalse
loadingWhether to show loading statebooleanfalse
sizeSwitch size'large' | 'default' | 'small''default'
widthSwitch total widthnumber | string—
inline-promptWhether to show icons/text inside the handle (max 3 chars)booleanfalse
active-iconIcon displayed when status is ON (ignores active-text)string | Component—
inactive-iconIcon displayed when status is OFF (ignores inactive-text)string | Component—
active-action-iconIcon displayed inside the sliding handle when ONstring | Component—
inactive-action-iconIcon displayed inside the sliding handle when OFFstring | Component—
active-textText displayed when switch is ONstring—
inactive-textText displayed when switch is OFFstring—
active-valueValue when status is ONboolean | string | numbertrue
inactive-valueValue when status is OFFboolean | string | numberfalse
nameForm name attributestring—
validate-eventWhether to trigger form validation on changebooleantrue
before-changeHook before toggle; returning false or rejecting stops toggle() => Promise<boolean> | boolean—
idInput IDstring—
tabindexInput tabindexstring | number—
aria-labelNative input aria-label equivalentstring—

Events ​

NameDescriptionParameters
changeCallback function when switch state changes(value: boolean | string | number) => void

Slots ​

NameDescription
active-actionCustom content for the sliding handle (Action) when ON
inactive-actionCustom content for the sliding handle (Action) when OFF
activeCustom content when ON (inside handle if inline-prompt, else right side)
inactiveCustom content when OFF (inside handle if inline-prompt, else left side)

Expose ​

NameDescriptionType
focusFocus the Switch() => void
checkedWhether the Switch is currently activeComputedRef<boolean>

Theme Variables ​

VariableDescriptionDefault
--yh-switch-on-colorBackground color when activevar(--yh-color-primary)
--yh-switch-off-colorBackground color when inactivevar(--yh-border-color)
--yh-switch-widthTotal switch width40px
--yh-switch-heightTotal switch height20px
--yh-switch-button-sizeSliding handle size16px
--yh-switch-font-sizeFont sizevar(--yh-font-size-base)

Type Exports ​

NameDescription
YhSwitchPropsComponent props type
YhSwitchEmitsComponent emits type
YhSwitchSlotsComponent slots type
YhSwitchExposeComponent expose type
YhSwitchInstanceComponent instance type

Released under the MIT License.