Accessibility
The toggle follows the WAI-ARIA Switch pattern — a single control that flips a setting between on and off with immediate effect — and meets WCAG 2.1 AA. Built on a native <input type="checkbox">, an accessible toggle is reachable and operable from the keyboard, carries a label that names the setting it controls, and reports its on / off state to assistive technology — so the setting is clear whether the user is looking at it, listening to it, or tabbing through it.
For designers
Section titled “For designers”- All states (default, hover, on, disabled, focus) must maintain accessible contrast on every supported surface. Source: WCAG 1.4.3 Contrast (Minimum).
- The on / off state must never rely on colour alone — pair the colour change with the knob’s position, so the state survives for colour-blind users. Source: WCAG 1.4.1 Use of Color.
- Focus styles must stay visible, meet contrast requirements on every supported surface, and be clearly distinguishable from hover. Source: WCAG 2.4.7 Focus Visible.
- Use semantic colour tokens (e.g.
foreground/neutral/default) rather than fixed values, so the component adapts correctly across themes and surfaces.
For developers
Section titled “For developers”Build on a native <input type="checkbox"> and never recreate the control from <div> or <span> — the native element brings the role, state, and keyboard operability that assistive technology relies on. role="switch" is an optional enhancement on top of that native control, not a replacement for it. A toggle applies its change immediately, so don’t pair it with a Save step that implies the setting is pending. The per-element roles, names, and states are in the Labelling elements section below.
Keyboard interaction
Section titled “Keyboard interaction”| Key | Action |
|---|---|
| Tab / Shift + Tab | Move focus to the next / previous control |
| Space | Toggle the focused switch between on and off |
Interactive targets — the switch plus its label — must be at least 44 px high for comfortable touch use, comfortably clearing the WCAG AA minimum. Source: WCAG 2.5.8 Target Size (Minimum).
Focus order
Section titled “Focus order”A toggle is a single tab stop: focus reaches the switch itself, and its label is associated with the input rather than being a separate stop. The key that drives it is in the Keyboard interaction table above. Source: WCAG 2.4.3 Focus Order.
Labelling elements
Section titled “Labelling elements”Give every element the role, name, and state assistive technology needs.
Switch
A native <input type="checkbox"> exposes the control’s role and its on / off state automatically. Add role="switch" so the state is announced as “on” / “off” — the native checked property carries the value, and the role maps it to aria-checked for you. Convey a non-interactive switch with the native disabled attribute, which also removes it from the tab order. Don’t move state to aria-* when the native attribute already carries it.
Label
The toggle takes its accessible name from the associated <label>, wired with for/id or by wrapping the input. Keep the label visible and self-describing, and phrase it as the setting being controlled (“Notifications”) rather than an action — never leave the name to a title or placeholder, and never replace it with an icon-only control.
Supporting and error text
The .is-error class is a visual cue only. Pair it with aria-invalid="true" and connect the message to the input with aria-describedby, so the failure is announced after the label and conveyed to assistive technology rather than by colour alone.
Source: WCAG 4.1.2 Name, Role, Value.