Switch
Accessible React switch for a single binary setting that applies immediately, with label, helper text, and states. Built on Radix and mirrored in RTL.
Switch flips one boolean that takes effect right away. For a choice confirmed on submit, use Checkbox instead.
When to use
Use Switch for a setting that takes effect the moment it changes: notifications on or off, dark mode, or showing archived items. If the choice is saved when a form is submitted, use Checkbox, because a switch implies an immediate result.
Label the setting, not the states. "Email alerts" is clearer than "On/Off".
Examples
Props
Props declared by Switch. Native attributes of the underlying element pass through.
| Prop | Type | Default | Description |
|---|---|---|---|
label | react.ReactNode | Visible label, sits beside the track, associated via htmlFor/id. | |
helperText | react.ReactNode | Hint shown below the row. Hidden while an error message is showing. | |
errorMessage | react.ReactNode | Message shown below the row when error is true. | |
error | boolean | Marks the field invalid: sets aria-invalid and error styling. | |
asChild | boolean | ||
checked | boolean | ||
defaultChecked | boolean | ||
required | boolean | ||
onCheckedChange | (checked: boolean) => void |
Accessibility
Switch exposes role="switch" with aria-checked, so screen readers announce it as a switch and read its state. Space toggles it, and the label is associated so clicking it works.
The thumb moves along the reading direction, so the on position sits at the inline end in RTL. The thumb position carries the state as well as the color.