1. Government Frontend Component Guide
  2. Accordion (experimental)

Component

Accordion (experimental)

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

This component is based on the design system accordion component and is currently experimental. If using this component, please feed back any research findings to the Design System team.

Search for usage of this component on GitHub

How it looks (preview all)

Writing well for the web

This is the content for Writing well for the web.

Writing well for specialists

This is the content for Writing well for specialists.

Know your audience

This is the content for Know your audience.

How people read

This is the content for How people read.

How to call this component

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

GOV.UK Design System

This component incorporates components from the GOV.UK Design System:

Accessibility acceptance criteria

The accordion must:

  • accept focus
  • be usable with a keyboard
  • indicate when they have focus
  • be usable with touch
  • be usable with voice commands
  • have visible text
  • indicate to users that each section can be expanded and collapsed
  • inform the user when a step has been expanded or collapsed
  • be readable when only the text of the page is zoomed in

Section headings must use a button element:

  • so that sections can be toggled with the space and enter keys
  • so that sections can’t be opened in a new tab or window

When JavaScript is unavailable the component must:

  • be fully expanded
  • not be marked as expandable

Links in the component must:

  • accept focus
  • be focusable with a keyboard
  • be usable with a keyboard
  • indicate when they have focus
  • change in appearance when touched (in the touch-down state)
  • change in appearance when hovered
  • be usable with touch
  • be usable with voice commands
  • have visible text

Other examples

With supplied identification (preview)

An id is optional as it’s automatically generated, but it can be supplied if a specific id is required.

The id must be unique across the domain of your service - this is because as the open / closed state of individual instances of the accordion persists across page loads using localStorage.

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.

Writing well for the web

This is the content for Writing well for the web.

Writing well for specialists

This is the content for Writing well for specialists.

Know your audience

This is the content for Know your audience.

How people read

This is the content for How people read.

<%= render "govuk_publishing_components/components/accordion", {
  id: "with-supplied-id-thats-unique-across-the-domain",
  items: [
    {
      heading: {
        text: "Writing well for the web"
      },
      content: {
        html: sanitize("<p class='govuk-body'>This is the content for Writing well for the web.</p>")
      },
      data_attributes: null
    },
    {
      heading: {
        text: "Writing well for specialists"
      },
      content: {
        html: sanitize("<p class='govuk-body'>This is the content for Writing well for specialists.</p>")
      },
      data_attributes: null
    },
    {
      heading: {
        text: "Know your audience"
      },
      content: {
        html: sanitize("<p class='govuk-body'>This is the content for Know your audience.</p>")
      },
      data_attributes: null
    },
    {
      heading: {
        text: "How people read"
      },
      content: {
        html: sanitize("<p class='govuk-body'>This is the content for How people read.</p>")
      },
      data_attributes: null
    }
  ]
} %>

With summary (preview)

Adds a subheading below each section heading.

<%= render "govuk_publishing_components/components/accordion", {
  items: [
    {
      heading: {
        text: "Understanding agile project management"
      },
      summary: {
        text: "Introductions, methods, core features."
      },
      content: {
        html: sanitize("<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>")
      },
      data_attributes: null
    },
    {
      heading: {
        text: "Working with agile methods"
      },
      summary: {
        text: "Workspaces, tools and techniques, user stories, planning."
      },
      content: {
        html: sanitize("<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>")
      },
      data_attributes: null
    },
    {
      heading: {
        text: "Governing agile services"
      },
      summary: {
        text: "Principles, measuring progress, spending money."
      },
      content: {
        html: sanitize("<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>")
      },
      data_attributes: null
    },
    {
      heading: {
        text: "Phases of an agile project"
      },
      summary: {
        text: "Discovery, alpha, beta, live and retirement."
      },
      content: {
        html: sanitize("<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>")
      },
      data_attributes: null
    }
  ]
} %>

With data attributes (preview)

Adds custom data attributes to the accordion to each section. Accepts an hash, so multiple attributes can be added.

The data_attributes hash is for the outermost element in the accordion.

Each item can also have a data_attributes hash. This is placed on the button that triggers the opening and closing - useful for differentiating between each section of the accordion.

Writing well for the web

This is the content for Writing well for the web.

Writing well for specialists

This is the content for Writing well for specialists.

Know your audience

This is the content for Know your audience.

How people read

This is the content for How people read.

<%= render "govuk_publishing_components/components/accordion", {
  data_attributes: {
    gtm: "gtm-accordion",
    ga: "ga-accordion",
    module: "govuk-accordion"
  },
  items: [
    {
      heading: {
        text: "Writing well for the web"
      },
      content: {
        html: sanitize("<p class='govuk-body'>This is the content for Writing well for the web.</p>")
      },
      data_attributes: {
        gtm: "gtm-accordion-item-1"
      }
    },
    {
      heading: {
        text: "Writing well for specialists"
      },
      content: {
        html: sanitize("<p class='govuk-body'>This is the content for Writing well for specialists.</p>")
      },
      data_attributes: {
        gtm: "gtm-accordion-item-2"
      }
    },
    {
      heading: {
        text: "Know your audience"
      },
      content: {
        html: sanitize("<p class='govuk-body'>This is the content for Know your audience.</p>")
      },
      data_attributes: {
        gtm: "gtm-accordion-item-3"
      }
    },
    {
      heading: {
        text: "How people read"
      },
      content: {
        html: sanitize("<p class='govuk-body'>This is the content for How people read.</p>")
      },
      data_attributes: {
        gtm: "gtm-accordion-item-4"
      }
    }
  ]
} %>

Different heading level (preview)

This will alter the level of the heading, not the appearance of the heading.

Writing well for the web

This is the content for Writing well for the web.

Writing well for specialists

This is the content for Writing well for specialists.

Know your audience

This is the content for Know your audience.

How people read

This is the content for How people read.

<%= render "govuk_publishing_components/components/accordion", {
  heading_level: 5,
  items: [
    {
      heading: {
        text: "Writing well for the web"
      },
      content: {
        html: sanitize("<p class='govuk-body'>This is the content for Writing well for the web.</p>")
      },
      data_attributes: null
    },
    {
      heading: {
        text: "Writing well for specialists"
      },
      content: {
        html: sanitize("<p class='govuk-body'>This is the content for Writing well for specialists.</p>")
      },
      data_attributes: null
    },
    {
      heading: {
        text: "Know your audience"
      },
      content: {
        html: sanitize("<p class='govuk-body'>This is the content for Know your audience.</p>")
      },
      data_attributes: null
    },
    {
      heading: {
        text: "How people read"
      },
      content: {
        html: sanitize("<p class='govuk-body'>This is the content for How people read.</p>")
      },
      data_attributes: null
    }
  ]
} %>

With section open (preview)

Adding expanded: true to the item will mean the section will default to being open, rather than closed. Once a user has opened or closed a section, the state of each section will be remembered - this can override a section’s default.

Writing well for the web

This is the content for Writing well for the web.

Writing well for specialists

This is the content for Writing well for specialists.

Know your audience

This is the content for Know your audience.

How people read

This is the content for How people read.

<%= render "govuk_publishing_components/components/accordion", {
  items: [
    {
      heading: {
        text: "Writing well for the web"
      },
      content: {
        html: sanitize("<p class='govuk-body'>This is the content for Writing well for the web.</p>")
      },
      expanded: true,
      data_attributes: null
    },
    {
      heading: {
        text: "Writing well for specialists"
      },
      content: {
        html: sanitize("<p class='govuk-body'>This is the content for Writing well for specialists.</p>")
      },
      data_attributes: null
    },
    {
      heading: {
        text: "Know your audience"
      },
      content: {
        html: sanitize("<p class='govuk-body'>This is the content for Know your audience.</p>")
      },
      data_attributes: null
    },
    {
      heading: {
        text: "How people read"
      },
      content: {
        html: sanitize("<p class='govuk-body'>This is the content for How people read.</p>")
      },
      data_attributes: null
    }
  ]
} %>

Condensed layout (preview)

This is for when a smaller accordion is required. Since smaller screens trigger a single column layout, this modifier only makes the accordion smaller when viewed on large screens.

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