Switch
A switch that turns a setting on or off at once, with its label beside it.
import { Switch } from "@butteryui/react";Demo
Text on the gift card lines up as you drag it.
When to use it
Use it for
- A setting that takes effect as soon as it's flipped: snap to grid, dark previews, sync
- A dense list of settings, such as a table's notification options, with size="sm"
Not for
- A choice in a form that waits for Submit: use Checkbox
- One of several options: use SegmentedControl
Examples
Cloud sync
A switch with a hint about what it does, which follows it as it's flipped.
Orders and stock back up as you work.
Order emails
A settings section: the first switch turns the emails on, and the ones under it pick what they cover.
Shop emails
Takes effect as soon as you flip a switch.
No emails
Snap to grid
A setting kept in state: it takes effect the moment it's flipped, and Restore default sets it back from outside.
Text on the gift card snaps to the 8px grid
Two sizes
A switch at md over a dense list of small ones, each turning one alert on or off at once.
1 of 3 alerts on
Variants and states
States
Off, on, with a hint, and disabled off and on. The thumb glides across on spring.snappy.
Orders and stock back up as you work.
Sizes
md, the default, is a 32×20 track beside a label-role label; sm is a 26×16 track beside 13px words, for a dense list. Both keep a 24px target.
As they're issued.
Props
Switch
| Prop | Type | Default | Description |
|---|---|---|---|
labelrequired | ReactNode | What it turns on, beside the switch. Pressing it flips the switch too. | |
hint | ReactNode | A hint under the label. | |
checked | boolean | Whether it's on. Pair with onCheckedChange to control it. | |
defaultChecked | boolean | false | Whether it starts on when uncontrolled. Defaults to false. |
onCheckedChange | ((checked: boolean) => void) | Called when it's turned on or off. | |
value | string | "on" | What it submits in a form while it's on. Defaults to "on". |
size | "sm" | "md" | "md" | "md" (the default), a 32×20 track beside a label-role label, or "sm", a 26×16 track beside 13px words,
for dense lists such as a table's settings. Its target stays 24px tall either way. |
It also takes Omit<ComponentPropsWithRef<"button">, "value" | "defaultValue" | "defaultChecked" | "onChange" | "children" | "type">.
Accessibility
A real switch (role switch) named by its label, which takes presses too; Space and Enter flip it. The track has a 3:1 edge while off and a 24px target. The thumb slides on spring.snappy and jumps with reduced motion. In forced colors it draws itself in system colors.
| Keys | What they do |
|---|---|
| Space or Enter | Turns it on or off |
Motion
Its selection indicator slides to the chosen option on `spring.snappy`, inside one track.
With reduced motion: The thumb lands at its new end at once instead of sliding.
Layout
The track is 32px wide and --bt-h-badge (20px, 18 compact) tall, with a hit area 24px tall, and its label sits 8px after it; at size="sm" the track is 26px wide and 4px under the badge height (16, 14 compact), its 13px label 6px after it, its hit area still 24px tall. A press on the label flips it too. The label and the hint wrap rather than truncate, and the hint lines up under the label.
Related
See it in the roastery demo's settings.