Components

Accordion
Experimental

This component is currently experimental because more research is needed to validate it.

The accordion component lets users show and hide sections of related content on a page.

<div class="govuk-accordion" data-module="govuk-accordion" id="accordion-default">
  <div class="govuk-accordion__section ">
    <div class="govuk-accordion__section-header">
      <h2 class="govuk-accordion__section-heading">
        <span class="govuk-accordion__section-button" id="accordion-default-heading-1">
          Writing well for the web
        </span>
      </h2>
    </div>
    <div id="accordion-default-content-1" class="govuk-accordion__section-content" aria-labelledby="accordion-default-heading-1">
      <p class='govuk-body'>This is the content for Writing well for the web.</p>
    </div>
  </div>
  <div class="govuk-accordion__section ">
    <div class="govuk-accordion__section-header">
      <h2 class="govuk-accordion__section-heading">
        <span class="govuk-accordion__section-button" id="accordion-default-heading-2">
          Writing well for specialists
        </span>
      </h2>
    </div>
    <div id="accordion-default-content-2" class="govuk-accordion__section-content" aria-labelledby="accordion-default-heading-2">
      <p class='govuk-body'>This is the content for Writing well for specialists.</p>
    </div>
  </div>
  <div class="govuk-accordion__section ">
    <div class="govuk-accordion__section-header">
      <h2 class="govuk-accordion__section-heading">
        <span class="govuk-accordion__section-button" id="accordion-default-heading-3">
          Know your audience
        </span>
      </h2>
    </div>
    <div id="accordion-default-content-3" class="govuk-accordion__section-content" aria-labelledby="accordion-default-heading-3">
      <p class='govuk-body'>This is the content for Know your audience.</p>
    </div>
  </div>
  <div class="govuk-accordion__section ">
    <div class="govuk-accordion__section-header">
      <h2 class="govuk-accordion__section-heading">
        <span class="govuk-accordion__section-button" id="accordion-default-heading-4">
          How people read
        </span>
      </h2>
    </div>
    <div id="accordion-default-content-4" class="govuk-accordion__section-content" aria-labelledby="accordion-default-heading-4">
      <p class='govuk-body'>This is the content for How people read.</p>
    </div>
  </div>
</div>
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Primary options
Name Type Description
id string Required. Must be unique across the domain of your service (as the expanded state of individual instances of the component persists across page loads using sessionStorage). Used as an id in the HTML for the accordion as a whole, and also as a prefix for the ids of the section contents and the buttons that open them, so that those ids can be the target of aria-labelledby and aria-control attributes.
headingLevel integer Heading level, from 1 to 6. Default is 2.
classes string Classes to add to the accordion.
attributes object HTML attributes (for example data attributes) to add to the accordion.
items array Required. An array of sections within the accordion. See items.
Options for items
Name Type Description
heading.text string Required. The title of each section. If heading.html is supplied, this is ignored. This is used both as the title for each section, and as the button to open or close each section.
heading.html string Required. The HTML content of the header for each section which is used both as the title for each section, and as the button to open or close each section.
summary.text string Text content for summary line. If summary.html is supplied, this is ignored.
summary.html string HTML content for summary line.
content.text string Required. The text content of each section, which is hidden when the section is closed. If content.html is supplied, this is ignored.
content.html string Required. The HTML content of each section, which is hidden when the section is closed.
expanded boolean Whether the section should be expanded upon initial load or not. Defaults to false.
{% from "govuk/components/accordion/macro.njk" import govukAccordion %}

{{ govukAccordion({
  id: "accordion-default",
  items: [
    {
      heading: {
        text: "Writing well for the web"
      },
      content: {
        html: "<p class='govuk-body'>This is the content for Writing well for the web.</p>"
      }
    },
    {
      heading: {
        text: "Writing well for specialists"
      },
      content: {
        html: "<p class='govuk-body'>This is the content for Writing well for specialists.</p>"
      }
    },
      {
      heading: {
        text: "Know your audience"
      },
      content: {
        html: "<p class='govuk-body'>This is the content for Know your audience.</p>"
      }
    },
      {
      heading: {
        text: "How people read"
      },
      content: {
        html: "<p class='govuk-body'>This is the content for How people read.</p>"
      }
    }
  ]
}) }}

When to use this component

Only use an accordion if there’s evidence it’s helpful for users to:

  • see an overview of multiple, related sections of content
  • show and hide those sections as needed

Accordions can work well for people who use a service regularly, for example users of caseworking systems who need to perform familiar tasks quickly.

When not to use this component

Accordions hide content from users and not everyone will notice them or understand how they work. For this reason do not use an accordion for content which is essential to all users.

Test your content without an accordion first. Consider if it’s better to:

  • simplify and reduce the amount of content
  • split the content across multiple pages
  • keep the content on a single page, separated by headings
  • use a list of links to let users navigate quickly to specific sections of content

Do not use the accordion component if the amount of content it would need to contain will make the page slow to load.

Accordions work best for simple content and links. Do not use accordions to split up a series of questions into sections. Use separate pages instead.

Accordions, tabs and details

Accordions, tabs and details all hide sections of content which a user can choose to reveal.

Consider using an accordion instead of tabs if users might need to view more than one section at a time.

You should also take into account the number of sections of content – accordions display vertically, so they can fit more sections than horizontal tabs.

Tabs may work better for users who need to switch quickly between 2 sections. Accordions push other sections down the page when they open, but tabs do not move which makes it easier to switch.

Consider using an accordion instead of the details component if there are multiple related sections of content. The details component might be better if you only have one or two sections of content. The details component is less visually prominent than an accordion, so tends to work better for content which is not as important to users.

How it works

There are 2 ways to use the accordion component. You can use HTML or, if you’re using Nunjucks or the GOV.UK Prototype Kit, you can use the Nunjucks macro.

The accordion component uses JavaScript. When JavaScript is not available, users will see all the content displayed with the section labels as headings.

Find out how your users interact with the content

Users might need the sections they have opened to stay open if they leave and then return to the page. You can configure the accordion component to stay open.

Do user research to find out the best order for the sections.

Use clear labels

Accordions hide content, so the labels need to be clear. If necessary, you can add a summary line to help users understand what is in the section.

<div class="govuk-accordion" data-module="govuk-accordion" id="accordion-with-summary-sections">
  <div class="govuk-accordion__section ">
    <div class="govuk-accordion__section-header">
      <h2 class="govuk-accordion__section-heading">
        <span class="govuk-accordion__section-button" id="accordion-with-summary-sections-heading-1">
          Understanding agile project management
        </span>
      </h2>
      <div class="govuk-accordion__section-summary govuk-body" id="accordion-with-summary-sections-summary-1">
        Introductions, methods, core features.
      </div>
    </div>
    <div id="accordion-with-summary-sections-content-1" class="govuk-accordion__section-content" aria-labelledby="accordion-with-summary-sections-heading-1">
      <ul class="govuk-list">
        <li>
          <a class="govuk-link" href="#">Agile and government services: an introduction</a>
        </li>
        <li>
          <a class="govuk-link" href="#">Agile methods: an introduction</a>
        </li>
        <li>
          <a class="govuk-link" href="#">Core principles of agile</a>
        </li>
      </ul>
    </div>
  </div>
  <div class="govuk-accordion__section ">
    <div class="govuk-accordion__section-header">
      <h2 class="govuk-accordion__section-heading">
        <span class="govuk-accordion__section-button" id="accordion-with-summary-sections-heading-2">
          Working with agile methods
        </span>
      </h2>
      <div class="govuk-accordion__section-summary govuk-body" id="accordion-with-summary-sections-summary-2">
        Workspaces, tools and techniques, user stories, planning.
      </div>
    </div>
    <div id="accordion-with-summary-sections-content-2" class="govuk-accordion__section-content" aria-labelledby="accordion-with-summary-sections-heading-2">
      <ul class="govuk-list">
        <li>
          <a class="govuk-link" href="#">Creating an agile working environment</a>
        </li>
        <li>
          <a class="govuk-link" href="#">Agile tools and techniques</a>
        </li>
        <li>
          <a class="govuk-link" href="#">Set up a team wall</a>
        </li>
        <li>
          <a class="govuk-link" href="#">Writing user stories</a>
        </li>
        <li>
          <a class="govuk-link" href="#">Planning in agile</a>
        </li>
        <li>
          <a class="govuk-link" href="#">Deciding on priorities</a>
        </li>
        <li>
          <a class="govuk-link" href="#">Developing a roadmap</a>
        </li>
      </ul>
    </div>
  </div>
  <div class="govuk-accordion__section ">
    <div class="govuk-accordion__section-header">
      <h2 class="govuk-accordion__section-heading">
        <span class="govuk-accordion__section-button" id="accordion-with-summary-sections-heading-3">
          Governing agile services
        </span>
      </h2>
      <div class="govuk-accordion__section-summary govuk-body" id="accordion-with-summary-sections-summary-3">
        Principles, measuring progress, spending money.
      </div>
    </div>
    <div id="accordion-with-summary-sections-content-3" class="govuk-accordion__section-content" aria-labelledby="accordion-with-summary-sections-heading-3">
      <ul class="govuk-list">
        <li>
          <a class="govuk-link" href="#">Governance principles for agile service delivery</a>
        </li>
        <li>
          <a class="govuk-link" href="#">Measuring and reporting progress</a>
        </li>
        <li>
          <a class="govuk-link" href="#">Spend controls: check if you need approval to spend money on a service</a>
        </li>
        <li>
          <a class="govuk-link" href="#">Spend controls: apply for approval to spend money on a service</a>
        </li>
        <li>
          <a class="govuk-link" href="#">Spend controls: the new pipeline process</a>
        </li>
        <li>
          <a class="govuk-link" href="#">Working across organisational boundaries</a>
        </li>
      </ul>
    </div>
  </div>
  <div class="govuk-accordion__section ">
    <div class="govuk-accordion__section-header">
      <h2 class="govuk-accordion__section-heading">
        <span class="govuk-accordion__section-button" id="accordion-with-summary-sections-heading-4">
          Phases of an agile project
        </span>
      </h2>
      <div class="govuk-accordion__section-summary govuk-body" id="accordion-with-summary-sections-summary-4">
        Discovery, alpha, beta, live and retirement.
      </div>
    </div>
    <div id="accordion-with-summary-sections-content-4" class="govuk-accordion__section-content" aria-labelledby="accordion-with-summary-sections-heading-4">
      <ul class="govuk-list">
        <li>
          <a class="govuk-link" href="#">How the discovery phase works</a>
        </li>
        <li>
          <a class="govuk-link" href="#">How the alpha phase works</a>
        </li>
        <li>
          <a class="govuk-link" href="#">How the beta phase works</a>
        </li>
        <li>
          <a class="govuk-link" href="#">How the live phase works</a>
        </li>
        <li>
          <a class="govuk-link" href="#">Retiring your service</a>
        </li>
      </ul>
    </div>
  </div>
</div>
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Primary options
Name Type Description
id string Required. Must be unique across the domain of your service (as the expanded state of individual instances of the component persists across page loads using sessionStorage). Used as an id in the HTML for the accordion as a whole, and also as a prefix for the ids of the section contents and the buttons that open them, so that those ids can be the target of aria-labelledby and aria-control attributes.
headingLevel integer Heading level, from 1 to 6. Default is 2.
classes string Classes to add to the accordion.
attributes object HTML attributes (for example data attributes) to add to the accordion.
items array Required. An array of sections within the accordion. See items.
Options for items
Name Type Description
heading.text string Required. The title of each section. If heading.html is supplied, this is ignored. This is used both as the title for each section, and as the button to open or close each section.
heading.html string Required. The HTML content of the header for each section which is used both as the title for each section, and as the button to open or close each section.
summary.text string Text content for summary line. If summary.html is supplied, this is ignored.
summary.html string HTML content for summary line.
content.text string Required. The text content of each section, which is hidden when the section is closed. If content.html is supplied, this is ignored.
content.html string Required. The HTML content of each section, which is hidden when the section is closed.
expanded boolean Whether the section should be expanded upon initial load or not. Defaults to false.
{% from "govuk/components/accordion/macro.njk" import govukAccordion %}

{{ govukAccordion({
  id: "accordion-with-summary-sections",
  items: [
    {
      heading: {
        text: "Understanding agile project management"
      },
      summary: {
        text: "Introductions, methods, core features."
      },
      content: {
        html:
        '<ul class="govuk-list">
            <li>
              <a class="govuk-link" href="#">Agile and government services: an introduction</a>
            </li>
            <li>
              <a class="govuk-link" href="#">Agile methods: an introduction</a>
            </li>
            <li>
              <a class="govuk-link" href="#">Core principles of agile</a>
            </li>
        </ul>'
      }
    },
        {
      heading: {
        text: "Working with agile methods"
      },
      summary: {
        text: "Workspaces, tools and techniques, user stories, planning."
      },
      content: {
        html:
        '<ul class="govuk-list">
            <li>
              <a class="govuk-link" href="#">Creating an agile working environment</a>
            </li>
            <li>
              <a class="govuk-link" href="#">Agile tools and techniques</a>
            </li>
            <li>
              <a class="govuk-link" href="#">Set up a team wall</a>
            </li>
            <li>
              <a class="govuk-link" href="#">Writing user stories</a>
            </li>
            <li>
              <a class="govuk-link" href="#">Planning in agile</a>
            </li>
            <li>
              <a class="govuk-link" href="#">Deciding on priorities</a>
            </li>
            <li>
              <a class="govuk-link" href="#">Developing a roadmap</a>
            </li>
        </ul>'
      }
    },
            {
      heading: {
        text: "Governing agile services"
      },
      summary: {
        text: "Principles, measuring progress, spending money."
      },
      content: {
        html:
        '<ul class="govuk-list">
            <li>
              <a class="govuk-link" href="#">Governance principles for agile service delivery</a>
            </li>
            <li>
              <a class="govuk-link" href="#">Measuring and reporting progress</a>
            </li>
            <li>
              <a class="govuk-link" href="#">Spend controls: check if you need approval to spend money on a service</a>
            </li>
            <li>
              <a class="govuk-link" href="#">Spend controls: apply for approval to spend money on a service</a>
            </li>
            <li>
              <a class="govuk-link" href="#">Spend controls: the new pipeline process</a>
            </li>
            <li>
              <a class="govuk-link" href="#">Working across organisational boundaries</a>
            </li>
        </ul>'
      }
    },
                {
      heading: {
        text: "Phases of an agile project"
      },
      summary: {
        text: "Discovery, alpha, beta, live and retirement."
      },
      content: {
        html:
        '<ul class="govuk-list">
            <li>
              <a class="govuk-link" href="#">How the discovery phase works</a>
            </li>
            <li>
              <a class="govuk-link" href="#">How the alpha phase works</a>
            </li>
            <li>
              <a class="govuk-link" href="#">How the beta phase works</a>
            </li>
            <li>
              <a class="govuk-link" href="#">How the live phase works</a>
            </li>
            <li>
              <a class="govuk-link" href="#">Retiring your service</a>
            </li>
        </ul>'
      }
    }
  ]
}) }}

If you struggle to come up with clear labels, it might be because the way you’ve separated the content is not clear.

Do not disable sections

Disabling controls is normally confusing for users. If there is no content for a section, either remove the section or, if this would be confusing for your users, explain why there is no content when the section is opened.

Research on this component

This component is experimental because there are different approaches to accordions in services. More research is needed to determine the best approach, or to know when a different approach works better.

The design for this component was originally created and tested by a team at the Government Digital Service (GDS) on the GOV.UK Service Manual and GOV.UK topic pages.

The team made sure the component is accessible, for example that users can interact with it using just the keyboard.

Known issues and gaps

The section headings can be mistaken for links, but are treated as buttons. This fails WCAG 2.1 success criterion 1.3.1 Info and Relationships. We plan to fix this issue by the end of June 2021.

The plus and minus icon is on the right side of the component, which means users of screen magnifiers might not see it.

The ‘Open all’ button reads out as ‘Open all sections’ for screen readers. This is potentially confusing for users as the visual content is different to what screen readers read out.

Next steps

Investigate the problem of some users not seeing the plus and minus icons on the right, for example people using screen magnifiers.

The plus and minus icons used in this component are the most commonly used accordion controls in government services.

However, more research is needed to find out how this compares to other approaches. For example GOV.UK Step by step navigation uses the words ‘Show’ and ‘Hide’ on the left side. Check the MOT history of a vehicle uses up and down arrows instead of plus and minus icons.

Help improve this page

To help make sure that this page is useful, relevant and up to date, you can:

Need help?

If you’ve got a question about the GOV.UK Design System, contact the team.