# Accessible Accordion: Buttons, Headings, State

Source: https://allyway.ai/glossary/accessible-accordion

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](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (Level A) applies: its [name, role and value](https://allyway.ai/glossary/name-role-value) must be programmatically determinable, and changes of state must reach assistive technologies. W3C names disclosure widgets explicitly as an example. The [Accordion Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) 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](https://allyway.ai/glossary/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.

> **Tip:** > **The native option: details and summary**
> For a single expandable section, the HTML elements `<details>` and `<summary>` bring the role, the state and the keyboard handling with them – no ARIA needed. Use the ARIA pattern when you need the full accordion behavior, such as only one panel open at a time.

## Examples

```html title="Example"
<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](https://allyway.ai/glossary/keyboard-navigation) works without extra code.

**Do:** Do

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.

**Don't:** Don't

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

Q: How do you make an accordion accessible?
A: 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.

Q: Should accordion headers be headings or buttons?
A: 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.

Q: Can I use details and summary for an accordion?
A: 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.

Q: Does an accordion need arrow-key navigation?
A: 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.

Q: Are accordions good for FAQ pages?
A: 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.
