Skip to content

Switch ​

On/off setting that applies at once, like a light switch. Use checkbox when the choice takes effect on submit, or for one item in a list.

Usage ​

vue
<Switch v-model="notifications" @update:model-value="save">Email notifications</Switch>

Props ​

PropTypeDefaultNotes
modelValuebooleanfalsev-model
size'md' | 'sm' | 'lg''md'Track and text size
disabledbooleanfalse
namestringnoneForm field name; without it the switch is not part of the form
valuestring'on'Submitted while on
classstringnoneApplied to the wrapping label

id, required (it needs name) and aria-* attributes go to the switch control, not the wrapper.

Slots ​

SlotContent
defaultThe setting's name; a click on it toggles the switch

Events ​

EventPayloadWhen
update:modelValuebooleanOn toggle

Tokens ​

None of its own. The track uses border-control off and primary on; the thumb is background off and primary-foreground on; corners are radius-full.

States ​

off, on; hover, focus-visible, disabled (off and on); three sizes; a label that wraps; no visible label (aria-label).

Keyboard ​

KeyAction
Space, EnterToggle

Accessibility ​

  • Renders role="switch" with aria-checked.
  • The default slot sits inside a label around the control, so it names the switch. Without a slot, pass aria-label.
  • Don't put "on" or "off" in the label; the state is announced.
  • A disabled switch dims its track; its label text turns muted-foreground, so it still meets contrast.
  • The thumb slides over --h-duration-fast, which is 0 ms under reduced motion.

Do ​

vue
<Switch v-model="darkMode">Dark mode</Switch>

Do not ​

vue
<!-- A switch in a form that saves on submit: use a checkbox. -->
<form @submit="save"><Switch v-model="terms">I accept the terms</Switch></form>