Components

Accordion

Overview

Overview

When to use

Use an accordion if it’s helpful for the user to see an overview of multiple, related sections of content and choose to show and hide sections that are relevant to them.

When not to use

Do not use an accordion for critical information or content that all users will need to see.

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 put accordions inside accordions, as it will make content difficult to find.

Do not use accordions to create step-by-step forms.

Accordions vs Tabs

If you decide to use one of these components, consider if:

• the user needs to look at more than one section at a time – an accordion can show multiple sections at a time, unlike tabs
• the user needs to switch quickly between sections – tabs can show content without pushing other sections down the page, unlike accordions
• there are many sections of content – accordions can fit more sections as they’re arranged vertically, unlike tabs which are arranged horizontally.

Principles

An accordion will usually start with all sections hidden. To show a section, the user can interact anywhere in the heading area.

Write the title like any other button text. Use sentence case, describe the content that will show, and keep it short. Users of screen readers might find it difficult to navigate the accordion if the title is too long.

Do not auto-close or auto-open accordions an do not auto-scroll the opened accordion to the top of the screen.

Suffix

Usage

Usage guidelines

Expand icon

Use the ‘chevron-down’ icon when the accordion is collapsed and the ‘chevron-up’ icon when it's expanded. Do not switch the icons and do not replace them with other icons.

Do

Don't

Don't

Nesting

Do not nest accordions within accordions, as it will make content difficult to find.

Don't

Titles

The title should be as brief as possible while still being clear and descriptive.

Do

Don't

Scrolling

When the accordion content is longer than the viewport the whole accordion should vertically scroll with the rest of the page. Content should not scroll inside of an individual panel and content should never scroll horizontally in an accordion.

Do

Don't

Don't

Accessibility

Keyboard

• Tab moves to the next section header; each header is a native button.
• Enter or Space expands or collapses the focused section.
• Arrow Down / Arrow Up move focus to the next or previous header of the same accordion, wrapping at the ends.
• Home / End move focus to the first or last header.

The arrow keys only move between the headers of their own accordion, never into a nested one.

Screen readers

Each header button carries aria-expanded ("expanded" / "collapsed") and aria-controls pointing at its panel. The panel is a role="region" labelled by the header text through aria-labelledby, so users who jump by landmark or region hear the section name. Collapsed panels use hidden="until-found": their text is not read while collapsed, but the browser's find-in-page still finds it and the script then expands that section. The chevron SVG is aria-hidden="true".

Using the example

• Ids (<id>-heading-N, <id>-content-N) must be unique on the page. The template derives them from the accordion id; give every hand-written copy its own.
• Keep the button inside the heading element, not the other way round, so the section is both a heading and a control.
• A suffix badge becomes part of the button's name. Keep it short, or give the badge its own screen reader text.

Known limits

The header is always an h2. If the accordion sits under an h2 or deeper, change the level in your copy so the page outline stays correct.