Overview
Accordions expand and collapse sections of content.
There are 2 types of accordions available in the Design System, single action accordions and accordion groups.
Single action accordion
A singular method of expanding and collapsing a piece of content with a title. These are best used for transcripts of videos, or for references at the footer of an article.
<!--
Light: <div class="qld__accordion-group">
Dark: <div class="qld__accordion-group qld__accordion-group--dark">
-->
<section class="qld__body">
<div class="container-fluid">
<div class="qld__accordion-group" id="Signle-action--example-1">
<div class="qld__accordion">
<h2 id="section__accordion-heading-2" tabindex="-1">
<button class="qld__accordion__title js-qld__accordion qld__accordion--closed"
aria-controls="Light-Example_1" aria-expanded="false" type="button">
Accordion heading 1
</button>
</h2>
<div class="qld__accordion__body qld__accordion--closed" id="Light-Example_1">
<div class="qld__accordion__body-wrapper">
Here <a href="#url">is</a> some accordion content
</div>
</div>
</div>
</div>
</div>
</section>
<section class="qld__body qld__body--dark">
<div class="container-fluid">
<div class="qld__accordion-group qld__accordion-group--dark" id="Signle-action--example-2">
<div class="qld__accordion">
<h2 id="section__accordion-heading-3" tabindex="-1">
<button class="qld__accordion__title js-qld__accordion qld__accordion--closed"
aria-controls="Dark-Example_1" aria-expanded="false" type="button">
Accordion heading 1
</button>
</h2>
<div class="qld__accordion__body qld__accordion--closed" id="Dark-Example_1">
<div class="qld__accordion__body-wrapper">
Here <a href="#url">is</a> some accordion content
</div>
</div>
</div>
</div>
</div>
</section>
Accordion group
A group of accordions that expand and collapse on click. Only the accordion that's clicked changes.
<!--
Light: <div class="qld__accordion-group">
Dark: <div class="qld__accordion-group qld__accordion-group--dark">
-->
<section class="qld__body">
<div class="container-fluid">
<div class="qld__accordion-group" id="accordion-group--example-1">
<div class="qld__accordion__toggle">
<button class="qld__accordion__toggle-btn qld__accordion__toggle-btn--closed" type="button" aria-expanded="false">Open all</button>
</div>
<div class="qld__accordion qld__margin-t-p">
<h2 id="section__accordion-heading-4" tabindex="-1">
<button class="qld__accordion__title js-qld__accordion qld__accordion--closed" aria-controls="LightExample_1" aria-expanded="false" type="button">
Accordion heading 1
</button>
</h2>
<div class="qld__accordion__body qld__accordion--closed" id="LightExample_1">
<div class="qld__accordion__body-wrapper">
Here <a href="#url">is</a> some accordion content
</div>
</div>
</div>
<div class="qld__accordion">
<h2 id="section__accordion-heading-5" tabindex="-1">
<button class="qld__accordion__title js-qld__accordion qld__accordion--closed" aria-controls="LightExample_2" aria-expanded="false" type="button">
Accordion heading 2
</button>
</h2>
<div class="qld__accordion__body qld__accordion--closed" id="LightExample_2">
<div class="qld__accordion__body-wrapper">
Here <a href="#url">is</a> some accordion content
</div>
</div>
</div>
<div class="qld__accordion">
<h2 id="section__accordion-heading-6" tabindex="-1">
<button class="qld__accordion__title js-qld__accordion qld__accordion--closed" aria-controls="LightExample_3" aria-expanded="false" type="button">
Accordion heading 3
</button>
</h2>
<div class="qld__accordion__body qld__accordion--closed" id="LightExample_3">
<div class="qld__accordion__body-wrapper">
Here <a href="#url">is</a> some accordion content
</div>
</div>
</div>
</div>
</div>
</section>
<section class="qld__body qld__body--dark">
<div class="container-fluid">
<div class="qld__accordion-group qld__accordion-group--dark" id="accordion-group--example-2">
<div class="qld__accordion__toggle">
<button class="qld__accordion__toggle-btn qld__accordion__toggle-btn--closed" type="button" aria-expanded="false">Open all</button>
</div>
<div class="qld__accordion qld__margin-t-p">
<h2 id="section__accordion-heading-7" tabindex="-1">
<button class="qld__accordion__title js-qld__accordion qld__accordion--closed" aria-controls="DarkExample_1" aria-expanded="false" type="button">
Accordion heading 1
</button>
</h2>
<div class="qld__accordion__body qld__accordion--closed" id="DarkExample_1">
<div class="qld__accordion__body-wrapper">
Here <a href="#url">is</a> some accordion content
</div>
</div>
</div>
<div class="qld__accordion">
<h2 id="section__accordion-heading-8" tabindex="-1">
<button class="qld__accordion__title js-qld__accordion qld__accordion--closed" aria-controls="DarkExample_2" aria-expanded="false" type="button">
Accordion heading 2
</button>
</h2>
<div class="qld__accordion__body qld__accordion--closed" id="DarkExample_2">
<div class="qld__accordion__body-wrapper">
Here <a href="#url">is</a> some accordion content
</div>
</div>
</div>
<div class="qld__accordion">
<h2 id="section__accordion-heading-9" tabindex="-1">
<button class="qld__accordion__title js-qld__accordion qld__accordion--closed" aria-controls="DarkExample_3" aria-expanded="false" type="button">
Accordion heading 3
</button>
</h2>
<div class="qld__accordion__body qld__accordion--closed" id="DarkExample_3">
<div class="qld__accordion__body-wrapper">
Here <a href="#url">is</a> some accordion content
</div>
</div>
</div>
</div>
</div>
</section>
Usage guidelines
When to use it
We recommend accordions be used sparingly for primary content on a page. While they can be appropriate for organising small, specific sections of content, accordions aren’t a suitable replacement for well formatted plain text. If a user needs all, or most of the information on the page it should be visible, not hidden inside an accordion.
Before using an accordion, consider whether the benefits outweigh the negative usability impacts.
- Hiding content makes it harder for a user to scan a webpage. If your content is hidden inside an accordion, it can be difficult for a user to scan the whole page for content relevant to them. Web browsers' ‘Find on page…' search functions don’t detect content hidden by accordions, making it harder for users to locate text.
- Accordions increase cognitive load. Forcing a user to click on each accordion to get the full text fragments their user experience, causing them to switch focus between accordions to get to the information. It’s also possible with hidden content, that a user might not see important information.
Accordions can be suitable when users need only a few key pieces of content on a single page. By hiding unimportant content within an accordion, users can efficiently focus on the few topics that matter (Loranger 2014).
Open all and close all button
If you have 3 or more accordion buttons in a stack, you can add the expand and close all button as an option.
When not to use it
- If the amount of content it would need to contain will make the page slow to load
- To split up a series of questions into sections, use separate pages instead
- With very short content, use lists or paragraphs
- With very long content, use tabs or separate pages
- With any other UI elements within the header
- For important information which if hidden could be missed
- Just to shorten a page
Accordions should be avoided when your audience needs most or all of the content on the page to answer their questions (Loranger 2014).
Research and rationale
Our accordion design and guidelines are based on the best practice and research outlined by the DTA (Digital Transformation Agency, 2018, Accordions section). The only modifications to this design was to include the addition of open all and close all functionality.
Single action accordions
Accordion elements on some websites collapse any open panels when another one is opened. This behaviour can seem unpredictable for some users, which is why our accordion components don’t behave in that way.
We want to make sure that users have full control over what content remains visible to minimise any confusion when content suddenly ‘disappears’ from view.
Iconography
We use an up and down chevron icon to represent our collapsible element, rather than a plus or minus, or arrows alternative.
Plus, and minus icons can better describe different functionality. For example, adding a dependent child to a form. The arrows are more closely aligned to navigation.
Classes
| Name | Description |
|---|---|
qld__accordion--closed | Closed state. |
qld__accordion--open | Open state. |
qld__accordion--alt | Variation for alt backgrounds. |
qld__accordion--dark | Variation for dark backgrounds. |
qld__accordion--dark-alt | Variation for dark-alt backgrounds. |
Accessible accordion requirements
Keep these considerations in mind if you're modifying the Design System or creating a custom component.
WCAG guidelines 2.1
1.3.1 Info and Relationships
Ensure that the information, structure, and relationships conveyed through the accordion's presentation can be programmatically determined or are available in text. For example, the relationship between the accordion header and the content it controls should be clear to assistive technologies.
1.4.3 Contrast (Minimum)
Ensure that text labels and icons in the accordion component have a sufficient colour contrast ratio against their background (at least 4.5:1 for normal text and 3:1 for large text).
2.1.1 Keyboard Accessible
Ensure that the accordion header buttons are focusable and can be expanded or collapsed using the keyboard, typically by pressing Enter or Space. Add keyboard support to allow users to use the arrow keys to navigate through the accordion headers.
2.4.3 Focus Order
Ensure that the accordion elements receive focus in an order that preserves meaning and operability. Typically, this means that focus moves to the contents of a section when it is expanded, and moves to the next header when a section is collapsed. When an accordion header is in focus, it must have a visible focus outline. This ensures that keyboard-only users can perceive which element within the accordion has the keyboard focus.
2.4.6 Headings and Labels
Headers should describe the topic or purpose and should be unique where possible, allowing users, particularly screen reader users, to navigate effectively.
3.2.2 On Input
Changes of context, such as expanding a panel, should be initiated only by user request and not automatically by a change in an input element or setting.
4.1.2 Name, Role, Value
For accordion headers that are interactive, use ARIA attributes to provide an accessible name, ensure the correct role is conveyed, and ensure that the component can be operated by assistive technologies. Additionally, use ARIA to indicate the expanded or collapsed state of the accordion.
Related components
References
Digital Transformation Agency (2018) Accoridon, Gold Design System (Formerly DTA), accessed 10 April 2023.
Laubheimer P and Budiu R. (2020). Accordion Icons: Definition, Best Practices, and Examples. Nielsen Norman Group, accessed 10 April 2023.
W3C (2018) Web Content Accessibility Guidelines (WCAG) 2.1, World Wide Web Consortium, accessed 10 April 2023.
Loranger H (2014). Accordion Icons: Definition, Best Practices, and Examples. Nielsen Norman Group, accessed 10 April 2023.
Last updated: May 2024