Accordion accessibility: use buttons + aria-expanded (not clickable divs)

Accordions are a common pattern for settings panels, FAQs, and “advanced options”. The most common accessibility failure is implementing the header as a styled <div> that only reacts to mouse clicks.

Why it matters

• Keyboard users need to reach the accordion headers with Tab and toggle them with Enter/Space.
• Screen reader users need the expanded/collapsed state announced. Without it, the UI feels like a guessing game.
• When content is collapsed, it should be actually hidden so users don’t tab into invisible controls.

Recommended pattern (minimal)

Use a real <button> for each accordion header, and update aria-expanded as it opens/closes. Connect the header to its panel with aria-controls.

<h3>
  <button type="button"
          aria-expanded="false"
          aria-controls="panel-1"
          id="acc-1">
    Graphics
  </button>
</h3>

<div id="panel-1"
     role="region"
     aria-labelledby="acc-1"
     hidden>
  <p>Colorblind mode: On</p>
</div>

Optional (but common): support ArrowUp/ArrowDown/Home/End to move focus between header buttons.

Common pitfalls

• Clickable div headers: a <div onclick> doesn’t work by default with keyboard navigation.
• State not exposed: forgetting aria-expanded means assistive tech can’t tell what’s open.
• Hidden content still tabbable: collapsing with CSS (e.g., height:0) can leave links/inputs reachable by Tab. Prefer [hidden] or otherwise remove from the tab order.
• Focus rings removed: don’t disable outlines; keep a visible focus indicator for the header buttons.

Related demos: toggle buttons · tooltips · modal focus