Accordion

Definition

An Accordion is a group of interactive headings with corresponding sections of content that are stacked vertically. Typically, these are used to reduce the amount of vertical space that the content occupies, which limits the amount of scrolling needed to bypass that content.

Each group in an Accordion is composed of two parts: an Accordion Header and an Accordion Panel. The Accordion Header describes the content of its associated Accordion Panel as well as controls showing and hiding that content. The Accordion Panel contains content that relates to the Accordion Header. Commonly, only one Accordion Panel is open or “expanded” at any given time.

A common use case for Accordions would be a Frequently Asked Questions (FAQ) section where each question is an Accordion header and the answer to that question is in the Accordion panel.

Usage Guidelines

Use Accordions when vertical real estate is limited or if the content contained in sections would cause excessive scrolling. They are also useful for cases where skimming headings would be the ideal way to search for information. Accordions are a good alternative to Tabs, especially when the headings are longer or the horizontal space is limited.

Some Accordions only allow one Accordion Panel to be visible at a time, which can be useful to avoid distraction but requires more care to ensure that the other Accordion Panels are collapsed when one is expanded.

Focus Expectations

Accordion Headers have visible focus states

Semantic Elements

heading elements (e.g. <h2>, <h3>)
button element (e.g. <button>)

ARIA Roles and Attributes

Accordion Header

The title is contained in a button element
The button is wrapped in a heading element
The button element is the only element inside the heading and any other content in the Accordion Header must be outside the heading element
The button element must have aria-expanded set to true when the associated Accordion Panel is visible otherwise aria-expanded must be false
The button element must have aria-controls set to the id of the element containing the Accordion Panel’s content

Accordion Panel

The element containing the Accordion Panel’s content must have a unique id
Optionally, use the “region” role with aria-labelledby set to the id of the associated Accordion Header’s button element as this helps provide structure to screen readers (but too many regions can defeat the purpose)

Keyboard Interactions

When focused on an Accordion Header
- Enter or Space: collapses or expands the related Accordion Panel
- Down Arrow or Up Arrow (optional): cycles focus through Accordion Headers
- Home (optional): moves focus to the first Accordion Header
- End (optional): moves focus to the last Accordion Header
Tab: moves focus to the next focusable element
Shift + Tab: moves focus to the previous focusable element