Switch

• Apply a setting at once, with no Save button, such as a notification preference.
• Get a complete settings row from one component: label and description on the left, switch on the right edge.
• Line up several settings so every switch sits on the same right edge.

• Options that only take effect when a form is submitted: use a Checkbox.
• Picking one of several modes, such as light, dark or system: use Segmented or a Radio Group.
• Toggling formatting in a toolbar: use a Toggle Group.

Controlled

Control it with checked and onCheckedChange when other UI reflects the setting.

const [digest, setDigest] = useState(true);<Switch checked={digest} onCheckedChange={setDigest} description="A summary of the week, every Monday at 9:00.">  Weekly digest</Switch>

Disabled, with the reason

Say why a setting is locked in description.

<Switch defaultChecked disabled description="Required for workspace owners.">  Sign-in alerts</Switch>

Bare switch

Leave out children when the layout already shows the label, and name it with aria-label.

<Switch aria-label="Dark mode" checked={dark} onCheckedChange={setDark} />

Switch

The switch is a 20×36px track with a 16px thumb inset 2px.

• The switch has role="switch" and aria-checked. A hidden input submits it with forms and works with Field validation.
• With children, a native <label> names it and clicking the label toggles it; description describes it through aria-describedby. Without children, pass aria-label.
• The focus ring draws around the track. A disabled switch drops to 50% opacity and its label dims.
• The bare track is 20px tall, so on touch screens use the labelled row, where the label is part of the target.

The thumb springs across on the snappy spring (350ms). While pressed, it stretches 4px toward where it's about to go, then the stretch closes behind it as it travels; only translate and clip-path animate. The track colour changes over 150ms on the standard curve. Disabled and read-only switches don't stretch. Reduced motion: the thumb jumps to its new side without a spring or a stretch, and only colours fade.

Pick Switch for a setting that applies immediately; pick Checkbox when the choice waits for a submit. Pass the label as children and helper text as description, and put row padding on className, which lands on the row.

Don't wrap it in your own label or flex row, and don't put a Label next to it: the row already handles naming, layout and the click target. Don't animate the thumb yourself.

The label column takes the remaining width and wraps; the switch keeps its size and stays on the label's first line, so it never squeezes on a narrow screen.

• Checkbox: an option that takes effect on submit.
• Segmented: one of a few modes, shown side by side.
• Field: adds validation messages around a control.