Switch
Turns a setting on or off at once.
Installation
The CLI installs the Radix or Base UI file to match your project.
If your project doesn't have Wisty UI's theme yet, add it once with npx shadcn@latest add @wisty/cosmos. Until then, components keep shadcn's default look. Installation has the details.
When to use
Use it
- For a setting that turns on or off and takes effect at once, like "Email me when a case I own closes".
- For a row in a settings list that enables a feature.
- In place of Lightning's checkbox toggle.
Don't use it
- The choice applies only when people save the form. Use Checkbox.
- People pick one of several options. Use Radio Group or Select.
- A toolbar button stays pressed, like Bold. Use Toggle.
Usage
Give every Switch a label: a Label with htmlFor set to the switch's id, or a Field with orientation="horizontal", as the Case notifications example shows. The change applies at once, so save from onCheckedChange.
import { Label } from "@/components/ui/label"
import { Switch } from "@/components/ui/switch"<div className="flex items-center gap-2">
<Switch id="out-of-office" />
<Label htmlFor="out-of-office">Out of office</Label>
</div>Examples
States
Every state SLDS draws: off, on, disabled, and disabled and on.
Sizes
The default size and the small one, set with `size="sm"`, both on.
API reference
Switch
| Prop | Type | Default |
|---|---|---|
size | "sm" | "default" | "default" |
Also takes every Radix Switch.Root (opens in a new tab) prop.
SLDS mapping
Switch is the faux track of slds-checkbox_toggle (slds-checkbox_faux). The track draws the thumb and SLDS's check mark itself, and a Label beside it is the toggle's label.
Known gaps:
- SLDS shows "Enabled" or "Disabled" under its toggle. Switch has no part for that text; add it beside the label when you need it.
| Prop | Value | SLDS | Notes |
|---|---|---|---|
size | default | slds-checkbox_toggle slds-checkbox_faux | SLDS's toggle. Use it unless the row is dense. |
size | sm | none | SLDS has one size. The same toggle at three quarters, for dense rows. |
Accessibility
- Name every switch with a visible label. The thumb and check mark are decoration; the state is in
aria-checked. - A disabled switch can't take focus. Say why the setting is unavailable in nearby text.
Motion
- The track color fades over 0.2s. The thumb doesn't slide, so it jumps to the other end.
- The fade runs with reduced motion too.
Responsive behavior
- The track keeps its width in a flex row, so a long label wraps beside it instead of squeezing it.
Rules
- Use it only for a change that applies at once. A switch in a form people save reads as "already done" and misleads.
- Never override the track's colors or size with utility classes. The tokens carry each theme;
size="sm"is the only size change.