Skip to main content

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>
Nunjucks macro options
Name Type Required Description
id string true id of the accordion
classes string false Classes to add to the accordion component
itemList Array<AccordionItem> true Accordion items to render
allButton AccordionButton false Settings for the show all / hide all button. If not specified the button will not render

AccordionItem

Name Type Required Description
title string true The title of the accordion item
titleTag string false The HTML tag that is used the title e.g. h2. Defaults to div
content string true The content of the accordion item
button AccordionItemButton false Settings for the button
attributes object false HTML attributes (for example data attributes) to add to the collapsible element
headingAttributes object false HTML attributes (for example data attributes) to add to the collapsible header element
contentAttributes object false HTML attributes (for example data attributes) to add to the collapsible content element

AccordionButton

Name Type Required Description
open string true Text to show when all of the items aren’t open
close string true Text to show when all of the items are open
attributes object false HTML attributes (for example data attributes) to add to the button

AccordionItemButton

Name Type Required Description
open string true Text for the button when the item is closed
close string true Text for the button when the item is open
attributes object false HTML attributes (for example data attributes) to add to the button
{% 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

Design System forum

Discuss ‘Accordion’ on GitHub