Switch
A Switch allows users to turn one setting on or off, such as payment reminders.
When to Use
- for a setting that applies as soon as it changes, such as “Send payment reminders”
- as the control at the end of a settings row, with its label and description at the start
When Not to Use
- for an option that is saved with its form (use a Checkbox)
- to choose one of several options (use a Radio Group)
- for a Button that stays pressed, such as bold in a toolbar (use a Toggle)
See Checkbox for a comparison of the Checkbox, the Switch, and the Radio Group.
Anatomy
| Element | Usage |
|---|---|
| Thumb | Required |
| Track | Required |
| Label* | Optional |
* A Switch with no visible label needs an aria-label.
Switch renders the track and the thumb. For the label, use a Label or the FieldLabel of a Field. A horizontal Field also lays out a settings row, with the label and a description at the start and the Switch at the end.
Sizes
A Switch has two sizes: default and sm.
Behavior
When users click the track or the label, the Switch changes state.
Content
| String | Rule | Example | Counterexample |
|---|---|---|---|
| Label | Sentence case | “Send payment reminders” | “Send Payment Reminders” |
| Label | Name the setting, not its state. The label should stay the same when the Switch changes. | “Send payment reminders” | “Reminders are on” |
Accessibility
Base UI’s Switch renders a span with the role switch, and a hidden input next to it for the form.
FieldLabel, connect a Label to its id with htmlFor, or set aria-label.Installation
npx shadcn@latest add @summit/switchUsage
import { Label } from '@/components/ui/label';
import { Switch } from '@/components/ui/switch';
<div className="flex items-center gap-2">
<Switch id="reminders" defaultChecked />
<Label htmlFor="reminders">Send payment reminders</Label>
</div>;API Reference
| Prop | Type | Default | Description |
|---|---|---|---|
size | 'default' | 'sm' | 'default' | The size of the track and of the thumb |
Other props are passed to the root of Base UI’s Switch. See the Base UI Switch documentation for checked, onCheckedChange, name, uncheckedValue, readOnly, and required.