Skip to main content

Accordion

Accordion lets readers reveal and collapse sections of content on demand. It helps manage information density on long pages while keeping the layout scannable, so people can focus on what matters to them without losing the rest of the structure.

Version: 2.0.0-beta
First section
Accordions help manage information density while keeping pages scannable.
Second section
Each section is a native <details> element, so keyboard and screen reader behaviour comes for free.
Third section
Set exclusive on the root to only allow one open at a time.

View in Storybook

When to Use​

Use an accordion when a page would otherwise overwhelm readers with long-form content that not everyone needs at once. It works well for grouped supporting detail – FAQs, settings panels, reference material, documentation sections – where the headings give readers a clear map and the panels hold optional depth.

Avoid Accordion for:

  • Critical information the reader must see – keep it visible in the main flow instead
  • Short content that fits without scrolling – the extra click costs more than it saves
  • Navigating between pages – use Link instead
  • Sequential, step-by-step flows – reach for a dedicated stepper pattern

Structure​

Accordion is a compound component built from a small set of parts that compose together:

  • Accordion: The root wrapper that groups items and controls how they behave together
  • Accordion.Item: A single collapsible section that holds a header and a panel
  • Accordion.Header: The clickable summary row with a chevron and a title
  • Accordion.Panel: The revealed content area shown when the item is open

All Accordion items support:

  • Independent open state by default – any combination of items can be open at once
  • Exclusive grouping on the root – opening one item closes the others
  • Controlled and uncontrolled modes at the item level – let consumers manage open state externally or let the component handle it
  • Density through the ancestor data-density attribute, keeping spacing in step with sibling components

Guidelines​

Independent and Exclusive​

By default, accordion items open and close independently of one another. This is the right behaviour when sections cover unrelated topics and a reader might reasonably want to compare or hold two open at the same time.

Switch to an exclusive group when the content is mutually exclusive, when keeping multiple panels open would confuse the layout, or when the surrounding container is short on vertical space.

Only one open at a time
Opening another section closes this one automatically.
Try me
The exclusive grouping uses the native HTML name attribute on <details>.
And me
No JS state machine needed.

View in Storybook

Controlled and Uncontrolled​

Accordion items work uncontrolled out of the box – the component remembers its own open state and you only need to set the initial value. Reach for a controlled item when the open state is part of broader UI logic: syncing with a URL parameter, restoring layout from saved preferences, or co-ordinating with another panel on the page.

Controlled item
Open state is held by the parent component. Currently: open.

View in Storybook

Density​

Accordion follows the active density on its ancestor, so spacing and sizing stay coordinated with the rest of the layout. Use the spacious default in standalone or content-led views, and switch to comfortable density inside dense surfaces like tools, settings panes, or side panels.

Spacious (default)

First section
Spacing and sizes pick up the ancestor data-density value.
Second section
Content hidden until opened.

Comfortable

First section
Spacing and sizes pick up the ancestor data-density value.
Second section
Content hidden until opened.

View in Storybook

Accessibility​

Accordion is built on the native <details> and <summary> elements, so disclosure semantics, keyboard support, and screen reader announcements come from the browser without bespoke ARIA wiring.

Keyboard support:

  • Tab: Move focus to and from the accordion header
  • Enter / Space: Toggle the focused section open or closed

Figma​

Components​

  • Accordion [EDS]: A single accordion row with the chevron, title, optional content panel, and full state coverage

Using the Accordion in Figma​

  1. In the Assets Panel, search for Accordion and drag the Accordion [EDS] component into your frame
  2. Stack multiple instances vertically to build a group – the top line on each row handles the shared divider
  3. Use the Open property to toggle a row between collapsed and expanded
  4. Use the State property to show Default, Hover, or Focus while documenting interactions
  5. Set the Title and Content text properties on each instance to match your real content

The component reads from the active theme mode on the containing frame, so colours, typography, and spacing follow the rest of your composition without manual overrides.

Do's and Don'ts​

Do
  • Write headers that clearly describe what is inside, so readers can decide whether to open a section
  • Reach for an exclusive group when only one panel should be visible at a time
  • Use accordions to support a primary layout, not to replace it
  • Keep panel content focused – one topic per item makes the structure scannable
Don't
  • Hide content people are likely to need on every visit – keep that visible in the main flow
  • Nest accordions inside accordions – the layering quickly becomes hard to follow
  • Stack a single accordion item on its own – a plain disclosure or section is clearer
  • Bury deeply nested headings inside a panel – flatten the content or split it across items