Accessible Accordion: Buttons, Headings, State
Also called: Accessible collapsible sections, FAQ accordion, Disclosure widget, Expandable sections
Definition
An accessible accordion is a set of collapsible sections whose headers are buttons inside headings, expose their expanded or collapsed state with aria-expanded and can be opened with the keyboard. Custom accordions fall under WCAG 4.1.2 Name, Role, Value at Level A.
An accessible accordion lets every visitor open and close its sections – by mouse, keyboard or screen reader. Accordions are everywhere: FAQ pages, product details, mobile menus, cookie settings. Too often the clickable header is a div with a click handler, so keyboard users cannot open it and screen reader users never hear that more content is hidden behind it.
What it means
An accordion built with script is a custom component, so WCAG 4.1.2 Name, Role, Value (Level A) applies: its name, role and value must be programmatically determinable, and changes of state must reach assistive technologies. W3C names disclosure widgets explicitly as an example. The Accordion Pattern of the ARIA Authoring Practices describes the structure:
| Part | What it needs |
|---|---|
| Header | A button that is the only element inside a heading (an h2, h3 … that fits the page's heading structure) |
| State | aria-expanded="true" when the panel is visible, "false" when it is hidden |
| Link to panel | aria-controls with the ID of the panel |
| Panel (optional) | role="region" with aria-labelledby pointing to its button – avoid it when many panels can be open at once (roughly more than 6), so the page does not fill up with landmarks |
| Panel that cannot close | aria-disabled="true" on its button, if the accordion does not allow collapsing an open panel |
Keyboard: Enter or Space opens or closes the panel of the focused header. Tab and Shift + Tab move through all focusable elements, including the content of open panels.
Examples
<h3>
<button type="button" id="acc-1" aria-expanded="false"
aria-controls="acc-panel-1">
How long does shipping take?
</button>
</h3>
<div id="acc-panel-1" role="region" aria-labelledby="acc-1" hidden>
<p>Orders within Austria arrive in 2–3 working days.</p>
</div>The script toggles aria-expanded and hidden together. A screen reader announces something like "How long does shipping take?, button, collapsed, heading level 3" – people know what it is, that it can be opened and where it sits in the page outline. Because it is a real <button>, keyboard navigation works without extra code.
Put a real button inside a heading, keep aria-expanded in sync with what is shown, hide closed panels with hidden or display: none, and show a visible focus outline on the headers.
Make a div or the heading itself clickable, show the state only with a rotating arrow icon, set states like aria-selected that a button cannot have, or hide closed panels only visually so screen readers still read them.
How to check an accessible accordion
Questions
How do you make an accordion accessible?
Use a <button> inside a heading for each header, set aria-expanded to true or false, link the button to its panel with aria-controls, and hide closed panels with hidden. The browser then handles the keyboard for you.
Should accordion headers be headings or buttons?
Both: the W3C pattern puts the button inside a heading. The heading lets people jump between sections, the button lets them open and close them.
Can I use details and summary for an accordion?
Yes, for simple expandable sections <details> and <summary> are accessible out of the box. For one-at-a-time behavior or custom animations, the ARIA accordion pattern gives you more control.
Does an accordion need arrow-key navigation?
It is not required. Enter, Space and the Tab key are the core of the W3C pattern for accordion headers; moving between headers with arrow keys is an optional extra. In tabs, by contrast, arrow keys are expected.
Are accordions good for FAQ pages?
They keep long pages short, but hidden answers are easy to miss. Clear question headings help, and so does the option to open all sections at once on long FAQ pages.
Related terms
Name, Role, Value: Controls Screen Readers Understand
Name, Role, Value is WCAG success criterion 4.1.2: for every user interface component, the name and role can be programmatically determined, user-settable states, properties and values can be programmatically set, and changes are announced to assistive technologies. It is Level A.
Read definition: Name, Role, Value: Controls Screen Readers UnderstandHeading Structure: Build a Clear Page Outline
Heading structure is the outline a page forms through its h1 to h6 elements. Each heading marks the start of a section, and its level shows where that section sits in the hierarchy.
Read definition: Heading Structure: Build a Clear Page OutlineKeyboard Navigation: WCAG 2.1.1 Explained
Keyboard navigation means that every function of a website can be reached and operated with a keyboard alone – usually with Tab, Shift+Tab, Enter, Space and the arrow keys. WCAG 2.1.1 requires it at Level A.
Read definition: Keyboard Navigation: WCAG 2.1.1 ExplainedAccessible Tabs: ARIA Roles and Arrow Keys
Accessible tabs are a tab interface whose tabs are exposed as a tab list with selected state, are operable with the keyboard and are connected to the panel they show. They fall under WCAG 4.1.2 Name, Role, Value at Level A, because custom tab widgets must tell assistive technology their role and state.
Read definition: Accessible Tabs: ARIA Roles and Arrow Keys