Skip to content

Accessibility

The accordion follows the WAI-ARIA APG Accordion pattern — a stack of headers that each show or hide a section of content — and meets WCAG 2.1 AA. An accessible accordion keeps every header reachable and toggleable from the keyboard, keeps assistive technology informed of each section’s expanded or collapsed state, and gives every header and panel an accessible name — so its structure is clear whether the user is looking at it, listening to it, or tabbing through it.

  • All accordion states (collapsed, expanded, hover, and focus) must maintain accessible contrast on every supported surface. Source: WCAG 1.4.3 Contrast (Minimum).
  • The open/closed state must never be conveyed by colour alone — pair it with a shape change such as the chevron rotation, a border, or a background shift. 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 accordion adapts correctly across themes and surfaces.

Build each header from native <details> and <summary>: the <summary> is the accordion’s header control and the parent <details> owns the open/closed state, so no extra ARIA is required. Use the name attribute on the <details> elements to make an exclusive group where only one section is open at a time. If you must build a custom accordion without <details>, put a <button> inside a heading of the appropriate level and wire it to its panel yourself — APG’s Accordion pattern then adds optional arrow-key and Home/End navigation between headers. The per-element roles, names, and states are in the Labelling elements section below. Mark the decorative chevron aria-hidden="true" so screen readers skip it.

Key Action
Enter / Space Toggle the focused accordion open or closed
Tab / Shift + Tab Move to the next / previous focusable element

Interactive targets 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).

Tab moves through the accordion toggle, its info button when the header has one, then any focusable content in the open panel, before reaching the next toggle. Opening a panel leaves focus on its toggle; don’t move it into the content. The panel and the toggletip don’t affect each other, and Escape closes the toggletip with focus staying on its info button. Source: WCAG 2.4.3 Focus Order.

Accordion title Link
  1. Toggle
  2. Link in the panel

Give every element the role, name, and state assistive technology needs.

Header trigger

The <summary> is the accordion’s header control; the browser gives it the toggle role and keeps its expanded/collapsed state in sync with the parent <details>. In a custom build, use a <button> with aria-expanded inside a heading and point aria-controls at its panel’s id. Its accessible name comes from the visible title text — never ship an icon-only header.

Content region

The panel is revealed in document order when its header expands and hidden when it collapses. In a custom build, give it role="region" with aria-labelledby referencing the header, so screen-reader users can find and identify each open section. Keep the header text self-describing so the region’s name stays meaningful.

Source: WCAG 4.1.2 Name, Role, Value.