Switch
Usage
Use a switch for a setting that takes effect immediately — notifications, showing retired vehicles on the map, auto-assigning work orders. Use a checkbox when the choice is only applied after pressing a Save or Submit button.
- The label names the setting that is on ("Text drivers about schedule changes"), never "On/Off" or a question.
- The setting changes the moment it is toggled — no Save button for it.
- If the change is saved to the server, set
aria-busy="true"on the switch while saving and revert with an error message if it fails.
Anatomy
- Track —
input[type=checkbox][role=switch].switch__input(native,appearance: none), 44 × 24px - Thumb —
::before, moves to the end when on - Label —
label.switch__label[for] - Hint (optional) —
.switch__hint
Examples
Hover and focus-visible are frozen with .is-hover and .is-focus-visible, which share their rules with the real pseudo-classes.
Switch
Only fleet admins can change this.
Drivers get an SMS when their vehicle's service date moves.
Sent to depot managers at 07:00.
<div class="switch [switch--label-start]">
<input class="switch__input" type="checkbox" role="switch" id="sms" aria-describedby="sms-hint" checked>
<label class="switch__label" for="sms">Text drivers about schedule changes</label>
<p class="switch__hint" id="sms-hint">Drivers get an SMS when their vehicle's service date moves.</p>
</div>
<!-- Async: while the change is saving -->
<div class="switch" aria-busy="true">…</div>API
| Hook | Values | Purpose |
|---|---|---|
.switch, .switch__input, .switch__label, .switch__hint | block / parts | One switch |
role="switch" | attribute (required) | Announced as on/off instead of checked |
.switch--label-start | modifier class | Label first, switch at the inline end (settings lists) |
checked, disabled | attribute | On; not operable (both values shown) |
aria-busy="true" on .switch | attribute | Saving: thumb pulses, pointer input ignored |
.is-hover | .is-focus-visible | docs-only class | Freezes a state |
Do and don't
Changes apply when you press Save.
Accessibility
| Key | Behavior |
|---|---|
| Tab | Moves to the switch |
| Space | Toggles on/off (native checkbox behavior) |
- Role:
switchon a native checkbox, so screen readers say "Text drivers about schedule changes, switch, on". - State is shown by thumb position and track fill, not color alone; the track border is 3:1 against the surface.
- Clicking the label toggles it; track 44 × 24px meets the 24px target minimum.
- Async failures: revert the switch and show an error message next to it, announced with
role="alert".
Tokens
| Custom property | Purpose |
|---|---|
--color-bg-muted, --input-border, --color-text-muted | Off track, border, thumb |
--color-action-primary-bg | -hover, --color-action-primary-fg | On track and thumb |
--icon-size-lg, --radius-full | Track size and shape |
--color-bg-subtle, --color-text-disabled | Disabled |
--motion-duration-fast, --opacity-disabled | Thumb movement, saving pulse |