Skip to the content

Switch

Switch is an on/off toggle: a native <input type="checkbox" role="switch"> drawn as a track and thumb, wrapped in a <label>. Use it for a setting that takes effect as soon as it flips, without a submit.
Forms

When to use

Use when
  • Turning an immediate-effect preference on or off (notifications, dark theme).
  • Each row of a settings panel controls one independent boolean.
Avoid when
  • The choice is saved later with a form — use Checkbox.
  • One of a few options must be picked — use Radio.
  • The control starts an action (save, send) — use Button.

Usage

<Switch name="wifi" label="Wi-Fi" checked={wifi} onChange={(e) => setWifi(e.target.checked)} />

Sizes

<Switch size="small" label="Small" />

Each size reads theme.component.switch.size.<size> (trackW, trackH, thumb, pad, in px); override one field with createTheme({ component: { switch: { size: { medium: { thumb: 20 } } } } }).

Color and locked state

The on track uses color (default primary); a validation variant (success, error) wins over it. A locked Switch (checked and disabled) keeps the thumb on but sits on the muted disabled fill.

<Switch name="beta" label="Beta" color="success" />
<Switch name="email" label="E-mail confirmed" checked disabled readOnly />

Accessibility

  • Screen readers announce a switch with an on/off state; Tab focuses it and Space toggles it.
  • Keyboard focus draws a :focus-visible outline around the track, kept in forced-colors mode.
  • The wrapping <label> names it from label; with no visible label, pass aria-label.

Properties

Placement props (area, alignSelf, justifySelf) apply to the label wrapper.

See also