Accordion

JSThis component requires JavaScript.

Component status:Ready

An Accordion groups content into sections and can be expanded and collapsed by the user.

Accordions are effective in shortening pages by reducing scrolling. Users decide if they want to read the content by expanding it or deferring it for later. For this reason, it is ideal for details that are not critical to the user for general understanding of the content.

Keep in mind that even though an Accordion shortens pages and reduces scrolling, it increases the interaction cost by requiring users to decide if the Accordion might contain information they are looking for.

Example

<div class="bux-accordion" data-allow-multiple>
	<h3 class="bux-accordion__heading">
		<button id="bux-accordion__trigger--1" type="button" class="bux-accordion__trigger" aria-controls="bux-accordion__panel--1" aria-expanded="false">
			<span class="bux-accordion__icon" aria-hidden="true"></span>
			<span class="bux-accordion__title"> Title of Accordion</span>
		</button>
	</h3>
	<div id="bux-accordion__panel--1" class="bux-accordion__panel" role="region" aria-labelledby="bux-accordion__trigger--1" hidden>
		Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
          Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 
	</div>
	<h3 class="bux-accordion__heading">
		<button id="bux-accordion__trigger--2" type="button" class="bux-accordion__trigger" aria-controls="bux-accordion__panel--2" aria-expanded="false">
			<span class="bux-accordion__icon" aria-hidden="true"></span>
			<span class="bux-accordion__title"> Title of Accordion</span>
		</button>
	</h3>
	<div id="bux-accordion__panel--2" class="bux-accordion__panel" role="region" aria-labelledby="bux-accordion__trigger--2" hidden >
		Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
          Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 
	</div>
	<h3 class="bux-accordion__heading">
		<button id="bux-accordion__trigger--3" type="button" class="bux-accordion__trigger" aria-controls="bux-accordion__panel--3" aria-expanded="false">
			<span class="bux-accordion__icon" aria-hidden="true"></span>
			<span class="bux-accordion__title"> Title of Accordion </span>
		</button>
	</h3>
	<div id="bux-accordion__panel--3" class="bux-accordion__panel" role="region" aria-labelledby="bux-accordion__trigger--3" hidden>
		Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
          Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 
	</div>
</div>

<div class="bux-accordion" data-allow-multiple>
  {% for item in items %}
    {% set triggerId = "bux-accordion__trigger--" ~ item.id %}
    {% set panelId = "bux-accordion__panel--" ~ item.id %}
    <h{{heading_level|default("2")}} class="bux-accordion__heading">
			<button id="{{ triggerId }}" type="button" class="bux-accordion__trigger" aria-controls="{{ panelId }}" aria-expanded="false">
        <span class="bux-accordion__icon" aria-hidden="true"></span>
        <span class="bux-accordion__title">
          {{ item.title }}
        </span>
      </button>
    </h{{heading_level|default("2")}}>
    <div id="{{ panelId }}" class="bux-accordion__panel" role="region" aria-labelledby="{{ triggerId }}" hidden>
      {{ item.content }}
    </div>
  {% endfor %}
</div>

Usage

Dos

• Use when there are several pieces of content related to a single topic, but the user only needs to read some of them (i.e. FAQs)
• Consider an Accordion as a complementary component to the main content (likely above it)
• It is fine to only use one Accordion if have a single element that you want to be expandable

Don’ts

• Don’t hide critical information within an Accordion that might be overlooked by the user
• Don’t include too much within an Accordion to reduce scrolling; consider nested Headings or another page. Long content on a mobile device can be problematic because the user must scroll far to either close the accordion or open another accordion.

Implementation notes

Each trigger and panel pair must be associated with each other by the following properties:

Trigger

• id="TRIGGER_ID" — a unique identifier for the trigger element
• aria-controls="PANEL_ID" — tells assistive technologies that this element controls another element
• aria-expanded="true|false" — tells assistive technologies that this element has been expanded or not

Panel

• id="PANEL_ID" — a unique identifier for the panel element
• role="region" — tells assistive technologies that this area in the document that the author has identified as significant
• aria-labelledby="TRIGGER_ID" — tells assistive technologies that this element is labeled by another element
• hidden — hides all non-active panels

Unless you are hand-coding this markup, you will want to generate a unique id for each pair and apply it via a for loop.

Multiple attribute

There is an optional attribute that you can add to the main <div> element.

• data-allow-multiple — This will allow for multiple accordion sections to be expanded at the same time

<div class="bux-accordion" role="presentation" data-allow-multiple></div>

Keyboard support

Key	Function
Space or Enter	When focus is on the accordion header of a collapsed section, expands the section.
Tab	Moves focus to the next focusable element. All focusable elements in the accordion are included in the page tab sequence.
Shift + Tab	Moves focus to the previous focusable element. All focusable elements in the accordion are included in the page tab sequence.
Down Arrow	When focus is on an accordion header, moves focus to the next accordion header. When focus is on last accordion header, moves focus to first accordion header.
Up Arrow	When focus is on an accordion header, moves focus to the previous accordion header. When focus is on first accordion header, moves focus to last accordion header.
Home	When focus is on an accordion header, moves focus to the first accordion header.
End	When focus is on an accordion header, moves focus to the last accordion header.

Accessibility

• Accessible Accordion Example
• Use the correct header levels appropriate for the accordion’s position in the document outline
• Limit the number of panels. Too many panels can result in difficulty for users that rely on keyboard-only navigation

References

• Nielson Norman Group Usability Article: Accordions Are Not Always the Answer for Complex Content on Desktops
• U.S. Web Design System (USWDS) Accordion