A switch means the change happens now. A checkbox means the change happens when you submit. That is the entire distinction, it is invisible in a screenshot, and getting it wrong is why some settings pages leave people unsure whether anything was saved.
65 public components on 21st have "switch" in the name. The visual variety is enormous; the rule is one sentence.
Switch or checkbox
Switch for a setting that applies immediately: notifications on, dark mode, a feature flag. It is a state, not a value to be collected.
Checkbox for anything inside a form that submits: terms accepted, options selected, a filter applied on submit. It is a value.
Two consequences follow, and both are commonly broken. A switch needs no Save button next to it, and pairing one with a Save button means one of the two is lying. And a checkbox should not animate like a switch, because the animation is what promises immediacy.
The settings guide makes the wider point: pick instant or explicit saving per section and never mix them on one screen.
The components
Material Design 3 Switch by Hossain Jahed is the platform-faithful implementation, and Apple Liquid glass switcher by dennysdionigi is the other platform's current look.
Toggle Switch by Daiwiik Harihar is the mechanical version with physics and an LED, Liquid Toggle by Deepak Chandwani is the gooey one, and lever-switch by Utkarsh Pandey is the lever.
The playful ones - Sky Toggle by Ravi Katiyar, Star Wars Toggle Switch by the same author - are the theme switchers that carry a whole scene, and the dark mode guide covers what that control specifically owes its reader.
The contract
Small, and broken often enough to be worth listing.
role="switch" with aria-checked, or a real checkbox input with the role applied. A div with a sliding knob announces nothing.
A label that says what it controls, not what state it is in. "Email notifications" with a checked state, not a control labelled "On".
Both states distinguishable without colour. Position carries most of it, which is why a switch works where a colour-only indicator does not, per the badge guide. Check it in greyscale.
A hit area of at least 44 by 44 points. The visible track is usually smaller than that, so the padding does the work.
Feedback on failure. A switch that applies immediately can fail immediately. Put it back and say why, rather than leaving it in a state the server does not share.
The one to avoid
A switch with three positions. If there are three states, that is a segmented control or a radio group, and forcing a third position into a two-state control produces a widget nobody can read - which the theme toggle case runs into whenever light, dark and system are squeezed into one slider.
Where else to look
The honest list, because the answer is not always us:
| Source | Best for | Trade-off |
|---|---|---|
| shadcn/ui Switch | The primitive with the role and keyboard correct | Plain by design |
| A styled checkbox input | Native semantics with no JavaScript | Less control over the animation |
| Radix / Base UI | Behaviour when you own the visuals | Unstyled |
| 21st | Platform-faithful, mechanical and playful variants | Quality varies by author, so preview before you take it |
Taking one
Every component page has a live preview and the code. Installing goes through the shadcn CLI against our registry:
That key comes from your 21st account, and installs require a membership. Set API_KEY_21ST once in your shell and the command works for anything in the catalogue.
Frequently asked
- When should you use a switch instead of a checkbox?
- A switch when the change applies immediately, such as notifications or dark mode; a checkbox when the value is collected and submitted with a form. A switch needs no Save button beside it, and pairing the two means one of them is lying about when the change happens.
- What does a switch need to be accessible?
- role="switch" with aria-checked, or a real checkbox input with the role applied, a label naming what it controls rather than its state, states distinguishable without colour since position carries most of it, and a hit area of at least 44 by 44 points.
- What happens if a switch fails to save?
- It has to go back and say why. A control that applies immediately can fail immediately, and leaving it in a state the server does not share is the worst outcome, because the reader has no reason to doubt what they can see.
- Can a switch have three states?
- No. Three states is a segmented control or a radio group. Squeezing a third position into a two-state slider produces a widget nobody can read, which is exactly what happens when light, dark and system are forced into one theme toggle.