Switch
updatedIs this a checkbox?
Open Props in the corner of the example to try color, size and disabled.
color fills the track when the switch is on, in Button's colours or your own. primary is the default. The edge takes the colour's text shade, which keeps 3:1 against the page where a bright warning track doesn't. Off, it keeps the --input edge, so a row of switches that are off reads as one set. An invalid switch turns red whatever its colour.
size runs from xs, 16px tall, to xl, 32px, in steps of 4px. md, the default, is 24px by 39px, between shadcn's switch and Material's; xl is Material's 52px by 32px. The width, handle, icons and state layer all scale with the height.
Installation
Usage
<script setup lang="ts">
import { Field, FieldLabel } from '@/components/ui/field'
import { Switch } from '@/components/ui/switch'
const airplane = ref(false)
</script>
<template>
<Field orientation="horizontal">
<Switch v-model="airplane" />
<FieldLabel>Airplane mode</FieldLabel>
</Field>
</template>
Use a switch when the change applies right away. If it waits for a Save button, use a Checkbox instead.
Turn it on, and the handle grows and slides across with a little bounce. Press it, and the handle swells. Hover and press get the same soft circle as Checkbox.
Inside a Field, it works as usual.
Examples
Icons
Use the checked-icon and unchecked-icon slots, or just one of them. The "on" icon spins in as the switch turns on. Add an "off" icon, and the handle stays big in both states to fit it.
Icons look best from lg up.
Description
For a settings row, put the label and description first and the switch after them; the label grows to push the switch to the end of the row.
Anonymous crash reports and feature usage, to help us fix problems.
Invalid
Touch target
Smaller than a finger? Add touch-target: expand when it stands alone, wrapper when it sits close to others. How it works.
With wrapper, the label moves along with the switch.
API Reference
class is also accepted and merged over the base classes.
Switch
| Prop | Default | Type and description |
|---|---|---|
| defaultValue | — | booleanThe starting state when |
| modelValue | — | boolean | nullWhether the switch is on, bound with |
| disabled | — | booleanDisables the switch. Also set by a disabled field. |
| id | — | stringOverrides the |
| value | — | stringThe value submitted with a form while the switch is on. |
| trueValue | — | booleanThe value |
| falseValue | — | booleanThe value |
| name | — | stringSubmits the switch with its form under this name. |
| required | — | booleanMarks the switch required. Also set by a required field. |
| color | "primary" | SwitchColor | (string & {})Colour role of the track while on. Any other name picks up a colour you declare on |
| size | "md" | SwitchSizeTrack height, from 16px for |
| touchTarget | — | "none" | "expand" | "wrapper" | nullGrows the pressable area to at least 48px without changing how the switch looks. |
| Event | Payload and description |
|---|---|
| update:modelValue | [payload: boolean]Fires when the switch turns on or off. |
| Slot | Scope and description |
|---|---|
| checked-icon | {}An icon shown in the handle while the switch is on. |
| unchecked-icon | {}An icon shown in the handle while it is off. Giving one keeps the handle at its larger size in both states. |
Props
- defaultValue
booleanThe starting state whenv-modelis not used.- modelValue
boolean | nullWhether the switch is on, bound withv-model.- disabled
booleanDisables the switch. Also set by a disabled field.- id
stringOverrides theidtaken from a surrounding field.- value
stringThe value submitted with a form while the switch is on.- trueValue
booleanThe valuev-modeltakes when on, instead oftrue.- falseValue
booleanThe valuev-modeltakes when off, instead offalse.- name
stringSubmits the switch with its form under this name.- required
booleanMarks the switch required. Also set by a required field.- color
"primary" SwitchColor | (string & {})Colour role of the track while on. Any other name picks up a colour you declare on[data-slot][data-color="<name>"]. Off, the edge stays--input; an invalid switch turnsdestructivewhatever its colour.- size
"md" SwitchSizeTrack height, from 16px forxsto 32px forxlin steps of 4px.mdis 24px, between shadcn's switch and Material's, andxlis Material's; the width and handle scale with the height.- touchTarget
"none" | "expand" | "wrapper" | nullGrows the pressable area to at least 48px without changing how the switch looks.wrapperalso reserves that space in layout;expandmay overlap neighbours.
Emits
- update:modelValue
[payload: boolean]Fires when the switch turns on or off.
Slots
- checked-icon
{}An icon shown in the handle while the switch is on.- unchecked-icon
{}An icon shown in the handle while it is off. Giving one keeps the handle at its larger size in both states.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| switch | data-state, data-color, data-size, data-disabled, data-touch-target, data-unchecked-icon | The track. |
| switch-thumb | data-state | The square the handle moves in. |
| switch-handle | — | The round handle. |