Switch
Last Updated: September 2026Switches toggle an immediate on/off setting with a track affordance.
Source CodeAnatomy
link- 1Track
- 2Thumb
- 3External label
Variants
linkOff
Unchecked until toggled.
On
defaultChecked for an enabled starting state.
Disabled
disabled prevents toggling in both on and off states.
Sizes
linkSwitches support 2 sizes: S and M.
Usage Guidelines
linkWhen to use
- •For immediate on/off settings that take effect without a submit button.
- •When a track affordance better communicates binary state than a checkbox.
- •In settings panels and preference rows.
When not to use
- •For form agreement / multi-select — use Checkbox.
- •For choosing among several options — use Select or Segmented Control.
- •For destructive one-shot actions — use Button with confirmation.
Place a visible label beside the switch and mirror it with aria-label.
Don't ship a bare Switch without an accessible name.
Use Switch when toggling applies immediately (preferences, visibility).
Don't use Switch for selecting items in a list — use Checkbox.
Behaviors
linkValue model
- •Uncontrolled: defaultChecked.
- •Controlled: checked + onCheckedChange.
- •Built on Base UI Switch Root.
Size
- •size="md" (default) — larger track and thumb.
- •size="sm" — compact for dense settings lists.
Styling constraints
- •className is omitted from the public props — do not pass className.
- •There is no built-in label; compose adjacent text yourself.
Content Guidelines
linkLabels
- •Name the setting, not the state (“Notifications”, not “On/Off”).
- •Keep labels parallel across a settings list.
Feedback
- •Apply the change immediately — don't pair a Switch with a Save button.
- •If the toggle can fail, surface the result with a Toast rather than reverting silently.
Accessibility
linkText & Labels
- •Always provide aria-label or associate a visible <label htmlFor=…>.
- •Visible text should match the accessible name.
ARIA attributes
- •Role and checked state come from Base UI Switch.
- •disabled is exposed and removes pointer interaction.
Keyboard Support
- •Tab → focus the switch.
- •Space / Enter → toggle.
WCAG Compliance Standards
FAQs
linkDoes Switch accept a label prop?
No. Compose adjacent text and set aria-label (or wire htmlFor to the control id).
What sizes exist?
sm and md (default). Pick sm for dense preference rows.
Can I pass className?
No — className is omitted from SwitchProps. Style via layout wrappers instead.