Accordion

An accordion is a series of expandable vertical panels, designed to save space on a page by hiding content and revealing it as required.

Demo & code Figma

Integrating content into agile workflows

Build content into the sprint from day one. Treat words as part of the product, not an afterthought. Add content tasks to the backlog and review them in stand ups alongside design and development.

Collaborate with product owners to define a clear Definition of Done for content. Encourage early reviews of copy within design critiques so language decisions move at the same pace as the interface.

Join daily stand ups and retrospectives to stay aligned
Include content tickets in sprint demos
Track feedback and updates using the same agile tools as your team

Designing simple paths through complex tasks

Start by naming the single outcome the user needs to achieve. Remove anything that doesn’t help them get there.

Structure the page like a conversation: set expectations up front, group related steps, and explain why you’re asking for information.

Lead with clear, task‑focused headings
Break long processes into confident, named steps
Use examples only where users typically hesitate

Partnering with subject matter experts

Make it easy for SMEs to help. Share a short agenda and a live doc. Ask them to walk a realistic scenario instead of describing the system.

Capture source links and who approved wording so changes are auditable. Follow up with a redline or prototype to make feedback fast.

Record facts with dates and owners
Translate jargon into plain language
Agree on the exact words users will see

Show code Hide code

Usage

Accordions can work well for people who use a service regularly, or who need to perform familiar tasks quickly.

The details based accordion is the default and recommended implementation.

Accordion and Show more

Accordion: organise multiple related sections with separate headings and independent expand and collapse controls.
Show more: reveal one block of supplementary detail tied to a summary.
Use Show more when the content is optional supporting detail rather than a set of navigable sections.

Guidance

only use an accordion if there’s evidence it’s helpful for users to see an overview of multiple, related sections of content
only use an accordion if there’s evidence it’s helpful for users to show and hide those sections as needed
test your content without an accordion first and consider if it’s better to simplify and reduce the amount of content
consider if it’s better to split the content across multiple pages
consider if it’s better to keep the content on a single page, separated by headings
consider if it’s better to use a list of links to let users navigate quickly to specific sections of content
consider if it’s better to use the Tab component 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.

Don't

use the accordion if the amount of content it would need to contain will make the page slow to load
use accordions to split up a series of questions into sections. Use separate pages instead
use with very short content, use lists or paragraphs
use with very long content, use tabs or separate pages
use an accordion for a single block of supplementary detail. Use Show more instead
add any other UI elements within the header
use where important information can be hidden and missed
use an accordion to shorten a page.

Collapse all/Expand all

The optional collapse all/expand all functionality allows users to perform the action to all accordions, reducing time and clicks to reach the required information. It can be removed or added as required.

This function should not be used to help users locate information within accordions. If a user is expanding multiple accordions because they are unsure of the content they contain, consider more descriptive titles or removing accordions all together and displaying the content separated by headings.

Open accordion pane on page load

By default, all panes in an accordion are closed.

Details based accordion: add the open attribute to any <details> element that should start open. The progressive enhancement layer leaves the native open state intact, adds role="region"/aria-labelledby to the panel, and wires the optional toolbar when present.
Legacy JavaScript accordion: add the .nsw-accordion__open class on the .nsw-accordion__title element. Without JavaScript, all panel content remains visible. When JavaScript runs, it hides panels and reopens only those marked with .nsw-accordion__open, then keeps aria-expanded/aria-hidden in sync.

Principles

Use clear labels

Accordions hide content, so the labels need to be clear. Ensure the headings used are brief and explicit about what is contained in the hidden panel. Intuitive headings help the user build a clear mental model of the content.

Do not disable sections

Accordions can be set open or closed. They can be configured to only allow 1 panel to be open at a time. Do not use with only 1 panel allowed to be open at once, if people need to compare items in different panels.

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.

Consider tabs if the user would likely need to flick between content sections.

Details variation (Recommended)

The details based accordion is the default and recommended implementation. It uses native <details> and <summary> elements for the disclosure pattern, which provides built in semantics, keyboard support and state announcement for assistive technologies. This version delivers the core expand and collapse interaction without requiring JavaScript and is progressively enhanced when JavaScript is available.

Why we included it

Semantic and accessible: uses the browser's native disclosure control so screen readers understand the role and state without extra ARIA attributes.
No-JS friendly: the main interaction (opening and closing panels) works even when JavaScript is disabled or blocked.
Progressive enhancement: when JavaScript is present, we add ARIA region/label associations to panels and wire optional "Expand all / Collapse all" controls without changing the native open/close behaviour.
Future proof: relies on well supported HTML elements instead of hidden form controls, which reduces the risk of implementation errors by consumers.

Limitations and trade offs

Styling hooks are constrained: browsers retain some control over <summary> behaviour and markers. While the Design System normalises the visual presentation, very heavy or unusual customisation of the header or marker is not supported.
Animation support varies between browsers: smooth height transitions for opening and closing rely on newer CSS capabilities. Where these are not available, some browsers will fall back to instant open and close rather than an animated transition.
Focus treatment is container based: due to how <summary> receives focus, we apply focus styles at the header or container level. Implementers should avoid additional overflow or clipping on parent containers that would cut off the focus ring.
Programmatic control is limited without JS: to open or close panels in response to validation, routing or other application events, you must use the JavaScript progressive enhancement layer or the legacy JavaScript accordion.

How to use

Use <details> for each item and <summary> for the clickable header, following the markup in the examples.
Optional: wrap multiple items in a container with .nsw-accordion--details. Use this when you want a grouped accordion and the "Expand all / Collapse all" toolbar. For a single item, the wrapper is not required.
Optional: add a toolbar container .nsw-accordion__toggle with "Expand all" and "Collapse all" buttons inside the wrapper. When JavaScript is available, these controls are wired up automatically.
Optional: add the .js-accordion-details hook to either the wrapper or a single <details> item to enable progressive enhancement (ARIA labelling and toolbar wiring).

Compatibility and support

The details based accordion is recommended for most use cases because it combines strong accessibility with reduced JavaScript dependence.
Some advanced animation or styling requirements may not be achievable with <details> and <summary>. In those cases, consider the legacy JavaScript accordion.
The details variant can safely coexist on the same page with the legacy JavaScript accordion without conflict.

Legacy JS-core variation (Supported)

The legacy JavaScript accordion (.js-accordion) is the original implementation and remains fully supported for backward compatibility and when advanced programmatic control or legacy behaviour is required.

This version manages state entirely through JavaScript, handling aria-expanded and aria-hidden attributes and adding roles for assistive technology.
Without JavaScript, all panel content remains visible. On init, JavaScript hides panels and reopens those marked with .nsw-accordion__open, then keeps aria-expanded/aria-hidden in sync as users interact.
While this approach supports consistent behaviour across browsers, it introduces additional load operations that can affect performance compared to the details based solution.
This variant is supported for now but is planned to be sunset next year; prefer the details based accordion for new work.

Accessibility

All components are responsive and designed to comply with WCAG 2.2 AA accessibility standards. Full compliance depends on using and configuring the components correctly. The details based accordion is the default implementation and meets these standards when implemented as intended, and the legacy JavaScript variant can also meet these standards when used correctly, but relies on additional scripting.

Support for accessibility features

Details based accordion

Uses native <details>/<summary> for built-in semantics, keyboard support and state announcement. Works without JavaScript; the progressive enhancement layer adds panel region/label ARIA and wires the optional "Expand all / Collapse all" controls without altering the native open state.

Without JavaScript, the details based accordion remains keyboard accessible through the native <summary> element.

Legacy JavaScript accordion

Retained for advanced scripting needs. It manages state via JavaScript, handling aria-expanded/aria-hidden and roles. Without JavaScript, panel content remains visible; when JavaScript initialises it hides panels and reopens those flagged with .nsw-accordion__open, then keeps attributes in sync as users interact. This extra scripting can add load overhead compared to the details based approach.