Accordion
Accordions let users show or hide sections of related content on the same page.
Open this example in a new window
<div id="accordion" class="accordion">
<button type="button" class="btn btn--secondary btn--small js-collapsible-all u-wa--@xxs u-mb-s u-d-no" data-close-all="Hide all" data-group="accordion">
<span class="btn__inner js-collapsible-all-inner">Show all</span>
</button>
<div id="accordion-1" class="collapsible js-collapsible collapsible--accordion" data-btn-close="Hide" data-group="accordion">
<div class="collapsible__heading js-collapsible-heading">
<div class="collapsible__controls">
<h2 class="collapsible__title">Total retail turnover</h2>
<span class="collapsible__icon">
<svg class="svg-icon" viewBox="0 0 7.5 12.85" xmlns="http://www.w3.org/2000/svg" focusable="false">
<path d="M5.74,14.28l-.57-.56a.5.5,0,0,1,0-.71h0l5-5-5-5a.5.5,0,0,1,0-.71h0l.57-.56a.5.5,0,0,1,.71,0h0l5.93,5.93a.5.5,0,0,1,0,.7L6.45,14.28a.5.5,0,0,1-.71,0Z" transform="translate(-5.02 -1.59)" />
</svg>
</span>
<button type="button" class="btn collapsible__btn btn--secondary btn--small js-collapsible-button u-d-no u-d-no@xxs@s">
<span class="btn__inner js-collapsible-button-inner">Show</span>
</button>
</div>
</div>
<div id="accordion-1-content" class="collapsible__content js-collapsible-content">
<h3 class="u-fs-r">Include:</h3>
<ul class="list">
<li class="list__item">VAT</li>
<li class="list__item">internet sales</li>
<li class="list__item">retail sales from outlets in Great Britain to <a href="#">customers abroad</a></li>
</ul>
<h3 class="u-fs-r">Exclude:</h3>
<ul class="list">
<li class="list__item">revenue from mobile phone network commission and top-up</li>
<li class="list__item">sales from catering facilities used by customers</li>
<li class="list__item">lottery sales and commission from lottery sales</li>
<li class="list__item">sales of car accessories and motor vehicles</li>
<li class="list__item">NHS receipts</li>
<li class="list__item">automotive fuel</li>
</ul>
</div>
</div>
<div id="accordion-2" class="collapsible js-collapsible collapsible--accordion" data-btn-close="Hide" data-group="accordion">
<div class="collapsible__heading js-collapsible-heading">
<div class="collapsible__controls">
<h2 class="collapsible__title">Food sales</h2>
<span class="collapsible__icon">
<svg class="svg-icon" viewBox="0 0 7.5 12.85" xmlns="http://www.w3.org/2000/svg" focusable="false">
<path d="M5.74,14.28l-.57-.56a.5.5,0,0,1,0-.71h0l5-5-5-5a.5.5,0,0,1,0-.71h0l.57-.56a.5.5,0,0,1,.71,0h0l5.93,5.93a.5.5,0,0,1,0,.7L6.45,14.28a.5.5,0,0,1-.71,0Z" transform="translate(-5.02 -1.59)" />
</svg>
</span>
<button type="button" class="btn collapsible__btn btn--secondary btn--small js-collapsible-button u-d-no u-d-no@xxs@s">
<span class="btn__inner js-collapsible-button-inner">Show</span>
</button>
</div>
</div>
<div id="accordion-2-content" class="collapsible__content js-collapsible-content">
<h3 class="u-fs-r">Include:</h3>
<ul class="list">
<li class="list__item">all fresh food</li>
<li class="list__item">other food for human consumption (except chocolate and sugar confectionery)</li>
<li class="list__item">soft drinks</li>
</ul>
<h3 class="u-fs-r">Exclude:</h3>
<ul class="list">
<li class="list__item">sales from catering facilities used by customers</li>
</ul>
</div>
</div>
<div id="accordion-3" class="collapsible js-collapsible collapsible--accordion" data-btn-close="Hide" data-group="accordion">
<div class="collapsible__heading js-collapsible-heading">
<div class="collapsible__controls">
<h2 class="collapsible__title">Alcohol, confectionery, soft drinks and tobacco sales</h2>
<span class="collapsible__icon">
<svg class="svg-icon" viewBox="0 0 7.5 12.85" xmlns="http://www.w3.org/2000/svg" focusable="false">
<path d="M5.74,14.28l-.57-.56a.5.5,0,0,1,0-.71h0l5-5-5-5a.5.5,0,0,1,0-.71h0l.57-.56a.5.5,0,0,1,.71,0h0l5.93,5.93a.5.5,0,0,1,0,.7L6.45,14.28a.5.5,0,0,1-.71,0Z" transform="translate(-5.02 -1.59)" />
</svg>
</span>
<button type="button" class="btn collapsible__btn btn--secondary btn--small js-collapsible-button u-d-no u-d-no@xxs@s">
<span class="btn__inner js-collapsible-button-inner">Show</span>
</button>
</div>
</div>
<div id="accordion-3-content" class="collapsible__content js-collapsible-content">
<h3 class="u-fs-r">Include:</h3>
<ul class="list">
<li class="list__item">chocolate and sugar confectionery</li>
<li class="list__item">tobacco and smokers’ requisites</li>
</ul>
</div>
</div>
</div>
{% from "components/accordion/_macro.njk" import onsAccordion %}
{{
onsAccordion({
"id": "accordion",
"allButton": {
"open": "Show all",
"close": "Hide all"
},
"itemsList": [
{
"title": "Total retail turnover",
"titleTag": "h2",
"content": "<h3 class=\"u-fs-r\">Include:</h3><ul class=\"list\"><li class=\"list__item\">VAT</li><li class=\"list__item\">internet sales</li><li class=\"list__item\">retail sales from outlets in Great Britain to <a href=\"#\">customers abroad</a></li></ul><h3 class=\"u-fs-r\">Exclude:</h3><ul class=\"list\"><li class=\"list__item\">revenue from mobile phone network commission and top-up</li><li class=\"list__item\">sales from catering facilities used by customers</li><li class=\"list__item\">lottery sales and commission from lottery sales</li><li class=\"list__item\">sales of car accessories and motor vehicles</li><li class=\"list__item\">NHS receipts</li><li class=\"list__item\">automotive fuel</li></ul>",
"button": {
"open": "Show",
"close": "Hide"
}
},
{
"title": "Food sales",
"titleTag": "h2",
"content": "<h3 class=\"u-fs-r\">Include:</h3><ul class=\"list\"><li class=\"list__item\">all fresh food</li><li class=\"list__item\">other food for human consumption (except chocolate and sugar confectionery)</li><li class=\"list__item\">soft drinks</li></ul><h3 class=\"u-fs-r\">Exclude:</h3><ul class=\"list\"><li class=\"list__item\">sales from catering facilities used by customers</li></ul>",
"button": {
"open": "Show",
"close": "Hide"
}
},
{
"title": "Alcohol, confectionery, soft drinks and tobacco sales",
"titleTag": "h2",
"content": "<h3 class=\"u-fs-r\">Include:</h3><ul class=\"list\"><li class=\"list__item\">chocolate and sugar confectionery</li><li class=\"list__item\">tobacco and smokers’ requisites</li></ul>",
"button": {
"open": "Show",
"close": "Hide"
}
}
]
})
}}
{% macro onsAccordion(params) %}
{% from "components/collapsible/_macro.njk" import onsCollapsible %}
<div id="{{params.id}}" class="accordion{{ ' ' + params.classes if params.classes }}">
{% if params.allButton is defined and params.allButton %}
{% from "components/button/_macro.njk" import onsButton %}
{% set attributes = params.allButton.attributes | default({}) %}
{% set attributes = attributes | setAttributes({
"data-close-all": params.allButton.close,
"data-group": params.id
}) %}
{{
onsButton({
"type": "button",
"text": params.allButton.open,
"classes": "btn--secondary btn--small js-collapsible-all u-wa--@xxs u-mb-s u-d-no",
"innerClasses": "js-collapsible-all-inner",
"attributes": attributes
})
}}
{% endif %}
{% for item in (params.itemsList if params.itemsList is iterable else params.itemsList.items()) %}
{{
onsCollapsible({
"isAccordion": true,
"id": params.id + "-" + (loop.index | string),
"button": item.button,
"attributes": item.attributes,
"headingAttributes": item.headingAttributes,
"contentAttributes": item.contentAttributes,
"title": item.title,
"titleTag": item.titleTag,
"content": item.content,
"group": params.id,
"saveState": params.saveState
})
}}
{% endfor %}
</div>
{% endmacro %}
When to use this component
Use this component when you have identified a strong user need to quickly scan large sections of content, by condensing them into an overview of section headings, and show and hide those sections as needed.
Accordions can benefit repeat users who need to regularly perform the same familiar tasks quickly, where they only need a few key pieces of the content to proceed.
When not to use this component
Accordions hide content from users and are not easily noticed and understood by everyone. So they should not be used if the content inside each accordion is critial to the user being able to progress with their task.
Test your content considering the following alternatives before using accordions:
- simplify the content to reduce down the amount
- separate the content with headings
- use page contents links to enable users to quickly to navigate to sections of content
- divide the content across multiple pages
Alternative components
Accordions, tabs and collapsible all hide sections of content which a user can show or hide.
Tabs may work better for users who need to switch quickly between sections because the position of their headings remains static, whereas the accordion headings move down the page as you open others.
Consider the number of sections you need to display. Tabs display horizontally so cannot display as many sections as accordions which display vertically. Also consider the use of your service on mobile devices. Tabs only display above 640px before their content is expanded and stacked vertically under headings.
Use the collapsible component if there is only one section of content that needs to be condensed.
How to use this component
The functionality of accordions is provided by grouping collapsible components together.
The accordion uses JavaScript so when it’s turned off, the sections of content are expanded. The collapsible.js file takes care of running the open all/close all button, if one is provided.
Use clear labels
Accordions hide content so make sure your section headings are clear so the user does not need to work hard to understand which heading to choose.
Research on this component
If you have conducted any user research using this component, please feed back your findings via the
Design System forum