Accordions

Accordions consist of a number of content panels, each of which can be expanded or collapsed vertically by the user.

Accordions help to save vertical space and reduce visual noise. Some accordions allow only a single panel to be expanded at a time, others allow multiple.

Accordion

Before you continue, please read Tablist widgets (or: tab panels, tabs) to understand why accordions simply are extended variants of tablists, providing a slightly different layout and (sometimes) expandability of multiple panels.

General requirements

The following requirements are based on well established best practices and the WAI-ARIA Authoring Practices Guide (APG): Accordion Pattern.

Accordions and Tablists share the same underlying logic: a trigger (header/tab) controls the visibility of a content panel. While they are structurally similar, accordions have specific requirements:

Multiple panels can be visible at the same time (optional).
Keyboard support: Users can navigate between accordion headers using Tab and toggle them with Enter or Space. (Optional but recommended: Arrow key navigation).

Proofs of concept

Update 2020: Due to the fact that Internet Explorer doesn’t need to be supported anymore (see Relevant combinations of screen readers and browsers), we now favor the Simple ARIA implementation.

Simple ARIA implementation

It is relatively simple to create a custom accordion implementation with ARIA:

Accordion with ARIA (APG pattern)

Show HTML code

Show CSS code

Show JS code

✔ (pass) ,

✔ (pass)

<p>
  <button>Focusable element before</button>
</p>

<section class="accordion-widget accordion" data-adg-accordion="flowers-accordion">
  <h2>Flowers</h2>

  <div class="accordion-item">
    <h3 class="accordion-header">
      <button id="accordion_header_rose" class="accordion-trigger" type="button" aria-expanded="true" aria-controls="accordion_panel_rose">
        <span class="indicator indicator-open" aria-hidden="true">-</span>
        <span class="indicator indicator-closed" aria-hidden="true">+</span>
        Rose
      </button>
    </h3>
    <div class="accordion-panel" id="accordion_panel_rose" role="region" aria-labelledby="accordion_header_rose">
      <p>A rose is a woody perennial flowering plant of the genus Rosa.</p>
      <p>
        <a href="https://en.wikipedia.org/wiki/Rose" target="_blank">Learn more about roses</a>
      </p>
    </div>
  </div>

  <div class="accordion-item">
    <h3 class="accordion-header">
      <button id="accordion_header_tulip" class="accordion-trigger" type="button" aria-expanded="false" aria-controls="accordion_panel_tulip">
        <span class="indicator indicator-open" aria-hidden="true">-</span>
        <span class="indicator indicator-closed" aria-hidden="true">+</span>
        Tulip
      </button>
    </h3>
    <div class="accordion-panel" id="accordion_panel_tulip" role="region" aria-labelledby="accordion_header_tulip" hidden>
      <p>Tulips are a genus of spring-blooming perennial plants.</p>
      <p>
        <a href="https://en.wikipedia.org/wiki/Tulip" target="_blank">Learn more about tulips</a>
      </p>
    </div>
  </div>

  <div class="accordion-item">
    <h3 class="accordion-header">
      <button id="accordion_header_sunflower" class="accordion-trigger" type="button" aria-expanded="false" aria-controls="accordion_panel_sunflower">
        <span class="indicator indicator-open" aria-hidden="true">-</span>
        <span class="indicator indicator-closed" aria-hidden="true">+</span>
        Sunflower
      </button>
    </h3>
    <div class="accordion-panel" id="accordion_panel_sunflower" role="region" aria-labelledby="accordion_header_sunflower" hidden>
      <p>A sunflower is a large annual plant.</p>
      <p>
        <a href="https://en.wikipedia.org/wiki/Sunflower" target="_blank">Learn more about sunflowers</a>
      </p>
    </div>
  </div>
</section>
<p>
  <button>Focusable element after</button>
</p>

body {
  padding: 20px;
  font-family: system-ui, sans-serif;
}

.accordion-widget > h2 {
  margin: 0 0 12px;
}

.accordion-item {
  margin: 0;
}

.accordion-trigger {
  appearance: none;
  background: none;
  font: inherit;
  color: inherit;
  display: flex;
  align-items: center;
  box-sizing: border-box;
  margin: 0;
  border: 1px solid black;
  padding: 6px 12px;
  width: 100%;
  cursor: pointer;
  text-align: left;
}

.accordion-trigger:hover {
  background: #fff9c4;
}

.accordion-trigger:focus-visible {
  outline: 2px dotted;
  outline-offset: 2px;
}

.indicator {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 1rem;
  flex: 0 0 1rem;
  margin-right: 8px;
  font-weight: normal;
}

.indicator-closed {
  display: none;
}

.accordion-trigger[aria-expanded='false'] .indicator-open {
  display: none;
}

.accordion-trigger[aria-expanded='false'] .indicator-closed {
  display: inline-block;
}

.accordion-header {
  margin: 0;
  font-size: 1.25rem;
  font-weight: 600;
}

.accordion-panel {
  border: 1px solid black;
  border-top: none;
  padding: 1rem;
  background: lightyellow;
}

.accordion-trigger[aria-expanded='true'] {
  background: lightyellow;
}

a:focus-visible,
button:focus-visible {
  outline: 2px dotted;
  outline-offset: 2px;
}

class AdgAccordion {
  constructor(el) {
    this.element = el
    this.triggers = Array.from(
      this.element.querySelectorAll('.accordion-trigger')
    )
    this.initTriggers()
  }

  initTriggers() {
    this.triggers.forEach(trigger => {
      const panelId = trigger.getAttribute('aria-controls')
      const panel = document.getElementById(panelId)

      const isExpanded = trigger.getAttribute('aria-expanded') === 'true'
      panel.hidden = !isExpanded

      trigger.addEventListener('click', () => {
        this.toggle(panel, trigger)
      })
    })
  }

  toggle(panel, trigger) {
    const isExpanded = trigger.getAttribute('aria-expanded') === 'true'
    trigger.setAttribute('aria-expanded', String(!isExpanded))
    panel.hidden = isExpanded
  }
}

const accordions = []

document
  .querySelectorAll('[data-adg-accordion]')
  .forEach(element => accordions.push(new AdgAccordion(element)))

Category	Result	Comments	Date
Keyboard only	✔ (pass) pass	-	2018-5-29
NVDA 2023.1 + FF 115	✔ (pass) pass	-	2023-8-3
NVDA 2021.2 + Chrome	✔ (pass) pass	-	2021-2-10
NVDA 2023.1 + Edge	✔ (pass) pass	-	2023-7-13
JAWS 2018.3 + FF ESR 52.7.3	✔ (pass) pass	-	2018-5-22
JAWS 2021.2 + Chrome	✔ (pass) pass	-	2021-2-10
JAWS 2023.1 + Edge	✔ (pass) pass	-	2023-7-13

Implementation details

This implementation follows the current APG approach and uses a real button in each header.

The button toggles aria-expanded (true/false).
The button uses aria-controls to reference the associated panel.
The panel uses role="region" and aria-labelledby to expose a clear relationship back to the controlling header button.
The panel visibility is synchronized with the semantic state using JavaScript.

Native HTML Disclosure Elements

For simple disclosure-like use cases, the native HTML <details> and <summary> elements are a solid, no-JavaScript option. You can find the technical specification and browser behavior in the MDN Web Docs for the Details element.

The summary element works as the interactive header.
The surrounding details element manages the expanded/collapsed state natively.
This removes the need for JavaScript compared to custom ARIA widgets.

Accordion with details and summary

Show HTML code

Show CSS code

Show JS code

<p>
  <button>Focusable element before</button>
</p>

<section class="accordion-widget accordion">
  <h2>Flowers</h2>

  <details class="accordion-item" open>
    <summary class="accordion-trigger">
      <span class="indicator indicator-open" aria-hidden="true">-</span>
      <span class="indicator indicator-closed" aria-hidden="true">+</span>
      <h3 class="accordion-header">Rose</h3>
    </summary>
    <div class="accordion-panel">
      <p>A rose is a woody perennial flowering plant of the genus Rosa.</p>
      <p><a href="https://en.wikipedia.org/wiki/Rose" target="_blank">Learn more about roses</a></p>
    </div>
  </details>

  <details class="accordion-item">
    <summary class="accordion-trigger">
      <span class="indicator indicator-open" aria-hidden="true">-</span>
      <span class="indicator indicator-closed" aria-hidden="true">+</span>
      <h3 class="accordion-header">Tulip</h3>
    </summary>
    <div class="accordion-panel">
      <p>Tulips are a genus of spring-blooming perennial plants.</p>
      <p><a href="https://en.wikipedia.org/wiki/Tulip" target="_blank">Learn more about tulips</a></p>
    </div>
  </details>

  <details class="accordion-item">
    <summary class="accordion-trigger">
      <span class="indicator indicator-open" aria-hidden="true">-</span>
      <span class="indicator indicator-closed" aria-hidden="true">+</span>
      <h3 class="accordion-header">Sunflower</h3>
    </summary>
    <div class="accordion-panel">
      <p>A sunflower is a large annual plant.</p>
      <p><a href="https://en.wikipedia.org/wiki/Sunflower" target="_blank">Learn more about sunflowers</a></p>
    </div>
  </details>
</section>

<p>
  <button>Focusable element after</button>
</p>

body {
  padding: 20px;
  font-family: system-ui, sans-serif;
}

.accordion-widget > h2 {
  margin: 0 0 12px;
}

.accordion-item {
  margin: 0;
  padding: 0;
  border: 0;
}

.accordion-trigger {
  appearance: none;
  background: none;
  font: inherit;
  color: inherit;
  display: flex;
  align-items: center;
  box-sizing: border-box;
  border: 1px solid #000;
  padding: 6px 12px;
  margin: 0;
  width: 100%;
  cursor: pointer;
  text-align: left;
  list-style: none;
  font-size: 1.25rem;
}

.accordion-header {
  margin: 0;
  font-size: inherit;
  font-weight: 600;
}

.accordion-trigger::marker {
  content: '';
}

.accordion-trigger::-webkit-details-marker {
  display: none;
}

.indicator {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 1rem;
  flex: 0 0 1rem;
  margin-right: 8px;
  font-weight: normal;
}

.indicator-closed {
  display: inline-block;
}

.indicator-open {
  display: none;
}

.accordion-trigger:hover {
  background: #fff9c4;
}

.accordion-item[open] > .accordion-trigger {
  background: lightyellow;
}

.accordion-item[open] > .accordion-trigger .indicator-open {
  display: inline-block;
}

.accordion-item[open] > .accordion-trigger .indicator-closed {
  display: none;
}

.accordion-panel {
  border: 1px solid #000;
  border-top: none;
  padding: 1rem;
  background: lightyellow;
}

.accordion-trigger:focus-visible,
a:focus-visible,
button:focus-visible {
  outline: 2px dotted;
  outline-offset: 2px;
}

// Native details/summary behavior requires no JavaScript for basic toggle behavior.

Implementation details

The panel lives in the default slot of <details> (no separate region role required for basic disclosure).
Each item uses <details> and <summary>; the open/closed state is exposed natively without aria-expanded.
Keyboard navigation: Browsers natively support Tab, Space, and Enter on the <summary>; arrow-key navigation between headers requires JavaScript.

Comparison: ARIA vs. Native HTML

Comparison of Implementation Methods

Comparison of Accordion Implementation Methods
Implementation Method	Advantages	Limitations
Custom ARIA Implementation	Full control over keyboard behavior (e.g. arrow keys). Better for complex layouts/nested widgets. Exact state control via JS.	Requires JavaScript for state and interaction. Higher maintenance (must handle all ARIA states manually). In Chrome with NVDA, if the virtual cursor is on an accordion button while keyboard focus is on a different element, activating the button can cause `aria-expanded` to be announced twice. No known fix exists.
Native Disclosure Elements (`<details>`)	Works without JavaScript. Native accessibility "out of the box". Minimal code footprint.	Limited styling options. No native support for "only one open" (requires JS). Default keyboard support is limited to Tab/Space/Enter. Adding `role="region"` (and similar ARIA attributes) to content inside `<details>` does not work reliably; workarounds are needed for explicit regions.

Legacy implementations (Historical)

Note: The following legacy variants are deprecated and provided for historical reference only.

For all new projects, use one of the recommended implementations above (ARIA or native <details>/<summary>, depending on your requirements).

Accordion with radio buttons (Legacy — for reference only)*
Multi accordion with checkboxes (Legacy — for reference only)

You are here:

Accordions

General requirements

Proofs of concept

Simple ARIA implementation

Implementation details

Native HTML Disclosure Elements

Implementation details

Comparison: ARIA vs. Native HTML

Comparison of Implementation Methods

Legacy implementations (Historical)

Previous/next navigation