use UI

Accordion

Also called collapsible group, expander list, faq list, toggle list

A set of headings that each reveal a panel of content, grouped so that they behave as one component.

Example

Standard delivery takes three to five working days. Express orders placed before 2pm ship the same day, and you get a tracking link as soon as the parcel leaves the warehouse.

With the switch off, opening one section closes the last — the only behaviour that is genuinely an accordion. Closed panels here are rendered with hidden="until-found", so searching the page for a word inside one makes the browser open it for you.

When to use it

  • The sections are parallel and short — an FAQ, a spec sheet, a list of policies — and no one reads all of them.
  • Vertical space is scarce and the headings work as a table of contents for what is below.
  • Settings that are grouped and rarely touched: collapsed by default is the honest state.
  • Only one section is relevant at a time, so closing the previous one is genuinely helpful rather than annoying.

When not to

  • Most of the content will actually be read. Every section then costs a click, and hidden content is measurably less read.
  • Two sections need to be compared. An exclusive accordion makes that impossible by design.
  • There is only one section — that is a disclosure, and wrapping it in a group buys nothing.
  • The content matters for search or deep links. Collapsed panels are not found by Ctrl+F unless you opt into `hiddenUntilFound`.

Trade-offs

  • Turns a long page into a scannable list of headings.
  • Recovers a lot of vertical space, which matters most on mobile.
  • Lets the reader choose what to spend attention on rather than scrolling past it.
  • Hidden content is read less. This is the cost, and it is usually underestimated.
  • Collapsed panels are invisible to in-page search by default.
  • Opening and closing shifts the layout underneath, and the heading you clicked can scroll out of view.
  • The exclusive variant means the user cannot keep two things open, which is a real constraint disguised as tidiness.

Accessibility

What this pattern needs in order to work for everyone.

Keyboard
  • Each trigger is a real `<button>`: Enter and Space toggle it, Tab moves between them.
  • Arrow-key navigation between headings is optional in the ARIA pattern — provide it if you like, but Tab must keep working.
  • Home and End jump to the first and last heading when arrow navigation is implemented.
Roles and state
  • Put each trigger inside a real heading element so screen reader users can navigate the accordion from the heading list.
  • `aria-expanded` on the trigger is the part screen readers actually rely on. `aria-controls` can only point at a panel that exists, so omitting it while a section is closed and unrendered is permitted.
  • A panel can take `role="region"` labelled by its trigger, but skip it when there are many sections: dozens of regions is noise, not structure.
Focus
Focus stays on the trigger when a panel opens — never move it into the panel. On close, focus must stay on the trigger too; if it lands on removed content, the screen reader drops to the top of the page.

In the wild

  • GOV.UK Design System — Ships an accordion and then spends most of the guidance telling you not to reach for it by default.
  • Stripe Docs — Collapses nested request and response fields, where nobody expands more than the two they need.

Compared with

Side-by-side breakdowns of patterns that solve a similar problem.