Switch
A toggle for a setting that applies immediately.
Switch turns a single setting on or off and applies the change straight away. If the change only takes effect on submit, the control is a Checkbox, not a switch.
States
Off by default
<Switch>Off by default</Switch>On by default
<Switch defaultSelected>On by default</Switch>Disabled
<Switch defaultSelected isDisabled>
Disabled
</Switch>Read-only
<Switch defaultSelected isReadOnly>
Read-Only
</Switch>Pass defaultSelected for uncontrolled use and isSelected with onChange
when the parent owns the state.
When to use
Use Switch for a single setting that applies the moment it changes.
Use something else when:
- The change only takes effect on submit. Use Checkbox.
- The reader chooses between more than two options. Use Segment.
Usage
Do
Label the setting, not the state. "Enable notifications" stays correct in both positions; "Notifications are on" contradicts itself when off.
Don't
Pair a switch with a Save button. A switch means the change has already happened — if it needs confirming, use a checkbox.
A switch should never need a confirmation dialog. If the action is dangerous enough to confirm, it is not a setting.
Props
| Prop | Type | Default |
|---|---|---|
childrenThe children of the component. A function may be provided to alter the children based on | TypeChildrenOrFunction<SwitchRenderProps> | Default— |
classNameThe CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the | TypeClassNameOrFunction<SwitchRenderProps> | Default— |
defaultSelectedWhether the element should be selected (uncontrolled). | Typeboolean | Default— |
inputRefA ref for the HTML input element. | TypeRef<HTMLInputElement | null> | Default— |
isDisabledWhether the input is disabled. | Typeboolean | Default— |
isReadOnlyWhether the input can be selected but not changed by the user. | Typeboolean | Default— |
isSelectedWhether the element should be selected (controlled). | Typeboolean | Default— |
Accessibility
Switch wraps React Aria's Switch, which renders a real checkbox input with
role="switch", so it is reachable by keyboard and toggles with Space. Passing
children labels it; without children, pass aria-label. In development, a
Switch with neither logs a console warning.
The thumb slides and the track changes colour over 150ms. Both are instant when the switch is toggled from the keyboard or the reader prefers reduced motion.