Skip to main content
Official government website
GovBB Design System
Menu

Accordion

Sections of related content, each collapsed behind its heading.

Examples
HTML and React
Group
Content
On this page

Preview

Accordion
Open in new tab

The accordion is built on the browser’s own details and summary elements, so it opens, closes and takes keyboard focus with no JavaScript. Sections animate open where the browser supports it, and open instantly everywhere else.

Each section takes its own heading level through headingLevel, so the accordion fits your page outline rather than forcing one. The default is h3.

Two props shape the whole accordion: variant for how the group is framed, and allowsMultipleExpanded for how many can be open at once. disabled works on the accordion or on a single section. There is one size and one row height everywhere; pick the heading level for your page outline, not for its look.

Usage

When to use

  • Use an accordion when a page holds several sections and most users only need one of them.
  • Use it to let users scan the headings and choose what to read.

When not to use

  • Do not hide content users need to read to complete their task, or content they will need to find with the browser's find-in-page.
  • Do not use an accordion for a single section. Use show and hide instead.

Framing: quiet, divided, boxed and cards

By default the accordion is quiet: a stack of pressable rows, each taking a hover fill and its own rounding, with nothing drawn between them. Three variant values draw borders instead.

Use divided for rules between sections, where headings run long and users scan the list rather than aim at it. Use boxed for one border around the whole group, where the accordion sits among other bordered blocks and needs to match them. Use cards to give each section its own bordered card, where sections are peers a user picks between rather than a list they read down.

Divided accordion
Open in new tab

The boxed and cards frames use the same markup with a different modifier class.

Cards accordion
Open in new tab

Icons and hints

A section heading can carry a decorative icon before it, and a hint line under it. Use a hint when the heading alone cannot say what is inside; front-load the heading anyway, because the hint is what users skip. Icons are hidden from screen readers, and an SVG drawn in currentColor follows the row’s hover and open colours. Hints are announced as part of the row.

Section with an icon and a hint
Open in new tab

Sections users cannot open

Set disabled on the accordion to stop every section opening, or on a single section for one that is not available yet. A disabled section is dimmed, drops out of the tab order and does not respond to a click, and it announces as disabled rather than as a heading users can act on.

Prefer explaining why a section is empty to disabling it. A user who cannot open a section learns nothing about what would put content in it.

Disabled section
Open in new tab

One section at a time

Set allowsMultipleExpanded={false} and the browser keeps one section open, closing the others as the user moves through them. It does that natively: the wrapper gives every section the same name, which is what the plain HTML example below sets by hand.

Leaving several sections open is the default, and the safer one for content users may want to compare.

Exclusive accordion
Open in new tab

Nesting

Accordions nest without any extra wiring: put one inside a section’s content and each group manages its own sections, so an exclusive outer group never closes because something opened inside it. Treat two levels as the limit; if you need a third, the page needs restructuring more than the accordion needs depth.

Nested accordion
Open in new tab

Best practices

Write headings users can choose between

The heading is the only thing a user sees before they open a section, so it has to describe what is inside. Write it in sentence case and front-load the words that distinguish one section from the next.

Keep sections independent

A user may open the third section first. Each section should make sense on its own rather than reading as step three of a sequence.