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.

HTML
Nunjucks

<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

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 `id`s of the section contents and the buttons that open them, so that those `id`s 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 2 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.

HTML
Nunjucks

HTML

<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

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 `id`s of the section contents and the buttons that open them, so that those `id`s 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 March 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:

share your research or feedback on GitHub
propose a change – read more about how to propose changes in GitHub

Need help?

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

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