Toggle buttons & switches

A button that turns something on and off — Mute, Follow, Bold — only looks toggled. The “on” look is carried by a CSS class or a colour swap, which the accessibility tree never sees. A screen reader announces it as a plain “Mute, button” in both states, so the user can’t tell whether mute is currently active before they press it, and gets no confirmation after. The fix is one attribute: a real <button> with aria-pressed="true" or "false", which makes it a toggle button announced as “Mute, pressed” or “Mute, not pressed”. Keep the visible label stable (“Mute”), and let aria-pressed carry the state — don’t swap the text between “Mute” and “Unmute”, or the name and state will say different things.

<!-- "Active" state is only a class; AT sees no change -->
<button type="button" class="toggle is-active">Mute</button>

<button type="button" aria-pressed="false">Mute</button>

<!-- when active -->
<button type="button" aria-pressed="true">Mute</button>

const btn = document.querySelector('.mute');
btn.addEventListener('click', () => {
  const on = btn.getAttribute('aria-pressed') === 'true';
  btn.setAttribute('aria-pressed', String(!on));
  // toggle the visual class too — state and style stay in sync
  btn.classList.toggle('is-active', !on);
});

The iOS-style sliding switch is the most cloned widget on the web, and it’s usually a <div> with a click handler. A bare <div> has no role, no accessible name, no state, and no place in the tab order, so a screen reader skips past it and a keyboard user can never reach it (4.1.2, 2.1.1). The robust fix is a native <input type="checkbox"> with a real <label>, styled to look like a switch — it’s focusable, keyboard-operable, and announced as checked/unchecked for free. When the on/off (rather than checked) semantics matter, add role="switch" so it is announced as “on/off”; otherwise the plain checkbox is enough.

<div class="switch" onclick="toggle(this)">
  <div class="switch__knob"></div>
</div>

<label class="switch">
  <input type="checkbox" name="wifi" checked>
  <span class="switch__track"></span>
  Wi-Fi
</label>

<!-- Native checkbox given switch semantics -->
<label><input type="checkbox" role="switch" checked> Wi-Fi</label>

<!-- Or a custom switch on a real button -->
<button type="button" role="switch" aria-checked="true">
  <span>Wi-Fi</span>
</button>

A toggle can have the right role and a starting state yet still fall silent when it’s used, because the script changes the visual but never updates aria-pressed or aria-checked. The control is focused, so nothing re-reads it; the user flips it and hears no confirmation, or hears the old state. The reliable fix is to update the control’s own state attribute on every change: when the focused element’s aria-pressed or aria-checked changes, assistive technology re-announces the new state automatically (4.1.2). Only when a toggle has a side effect somewhere else on the page — “Saved”, “Dark mode on” — do you add a polite live region (4.1.3); don’t bolt a redundant live region onto a control that already announces itself, or users hear the change twice.

<button type="button" aria-pressed="false" class="follow">Follow</button>
<script>
  follow.addEventListener('click', () => {
    follow.classList.toggle('is-on'); // visual only
    // aria-pressed never updated → AT still says "not pressed"
  });
</script>

follow.addEventListener('click', () => {
  const on = follow.getAttribute('aria-pressed') === 'true';
  follow.setAttribute('aria-pressed', String(!on));
  follow.classList.toggle('is-on', !on);
});

<button type="button" role="switch" aria-checked="false" id="dark">Dark mode</button>
<p id="theme-status" role="status" aria-live="polite"></p>
<script>
  dark.addEventListener('click', () => {
    const on = dark.getAttribute('aria-checked') !== 'true';
    dark.setAttribute('aria-checked', String(on));
    document.documentElement.classList.toggle('theme-dark', on);
    themeStatus.textContent = on ? 'Dark mode on' : 'Dark mode off';
  });
</script>