Accordion

An accordion is a vertically stacked list of items that utilizes show/hide functionality to reveal content.

Accordion has disclosures

Each section in an accordion should follow the disclosure pattern with some additional requirements that are detailed in this entry.

Panel

ARIA controls

Each accordion button should have an aria-controls attribute that points to the id of the associated panel.

Panel role

The best practice is to set the attribute role="region" on the panel element.

Accessibility label

The best practice is to set the aria-labelledby attribute pointing to the id of the associated button on each panel.

Headings structure and level

Each accordion button should be contained within a heading element whose level is one greater than the heading level of the section containing the accordion. The heading level should be the same for each accordion button. For example, if the accordion is contained within a section that begins with an h2 element, each accordion button should be contained within an h3 element.

Other than the button element, the heading element should not contain any other elements.

1<section>
2 <h2>Section heading</h2>
3 <div class="accordion">
4 <h3>
5 <button id="button1" aria-expanded="false" aria-controls="panel1">
6 What is the meaning of life?
7 </button>
8 </h3>
9 <div id="panel1" role="region" aria-labelledby="button1" class="collapsed">
10 <p>42</p>
11 </div>
12 <h3>
13 <button id="button2" aria-expanded="false" aria-controls="panel2">
14 How do you feel?
15 </button>
16 </h3>
17 <div id="panel2" role="region" aria-labelledby="button2" class="collapsed">
18 <p>I feel fine</p>
19 </div>
20 </div>
21</section>

If the accordion is build using native HTML details and summary elements, the heading element should be contained within the <summary> element rather than wrapping it since wrapping the summary element breaks the native behavior of the element.

1<section>
2 <h2>Section heading</h2>
3 <div class="accordion">
4 <details>
5 <summary>
6 <h3>What is the meaning of life?</h3>
7 </summary>
8 <p>42</p>
9 </details>
10 <details>
11 <summary>
12 <h3>How do you feel?</h3>
13 </summary>
14 <p>I feel fine</p>
15 </details>
16 </div>
17</section>

In that case make sure to set the display property of the heading element to inline to prevent the heading from being displayed as a block element.

1.accordion summary h3 {
2 display: inline;
3}

Toggle activation

Each section in an accordion should follow the disclosure pattern activation instructions.

Accordions with one active section

It is common for accordion implementations to only allow one expanded section at a time, where it can only be collapsed again by expanding another section. It is strongly recommended to permit the user to collapse the active section directly. However if this behavior is not desired, the active heading button should be disabled.

Summary of Tests

NameConformance LevelWCAG Success Criteria
Accordion has disclosuresA1.3.1 Info and Relationships
ARIA controlsA1.3.1 Info and Relationships
Panel roleBest practice4.1.2 Name, Role, Value
Accessibility labelBest practice4.1.2 Name, Role, Value, 1.3.1 Info and Relationships
Headings structureA1.3.1 Info and Relationships
Headings levelA1.3.1 Info and Relationships
Toggle activationA2.1.1 Keyboard, 4.1.2 Name, Role, Value, 1.3.1 Info and Relationships