Skip to content

  • VisualizationPage · Index
  • What’s newPage · Latest additions
  • Styles indexPage · Home
  • Compare stylesPage · Side by side
  • Patterns indexPage · Index
  • Articles indexPage · Index
  • Folio design systemPage · House system
  • Folio FoundationsPage · House system
  • Folio ComponentsPage · House system
  • Folio PatternsPage · House system
  • Folio MotionPage · House system
  • Folio ExamplesPage · House system
  • Folio ButtonsPage · Component
  • Folio Text fieldsPage · Component
  • Folio SelectPage · Component
  • Folio Checkboxes & switchesPage · Component
  • Folio Radio groupsPage · Component
  • Folio TabsPage · Component
  • Folio MenusPage · Component
  • Folio DialogsPage · Component
  • Folio TooltipsPage · Component
  • Folio Breadcrumbs & paginationPage · Component
  • Folio CardsPage · Component
  • Folio Badges & avatarsPage · Component
  • Folio Data tablesPage · Component
  • Folio Progress & loadingPage · Component
  • Folio FeedbackPage · Component
  • Folio Empty statesPage · Component
  • Folio MediaPage · Component
← UI patterns

Accordion

A vertical stack of headers that each expand and collapse a panel of content, revealing sections only as they are needed.

Single-open accordion, live. Each header is a real button in a heading; aria-expanded and the chevron track state. Opening one collapses the other.

Multi-open accordion with a close-all control. Any combination of panels can be open, better when users want to compare sections.

Behavior

Keyboard

Enter / Space
With focus on a header, toggle its panel. In a single-open accordion, opening one collapses the other.
Tab / Shift+Tab
Move to the next / previous focusable element. All focusable elements in the accordion are in the normal page tab sequence.
Down / Up Arrow
Optional: move focus between accordion headers, wrapping at the ends.
Home / End
Optional: move focus to the first / last header.
Parts

Accordion header

A label that also serves as the control for showing (and often hiding) its section. The title sits in an element with role=button, so it is operable and announced as a control.

Heading wrapper

Each header button is wrapped in a heading element with an aria-level appropriate to the page, so the headers form part of the document outline and screen-reader users can navigate by heading.

Accordion panel

The collapsible region of content tied to a header. It can take role=region with aria-labelledby pointing at its header, which helps when panels contain headings or nested accordions.

Expand/collapse icon

A chevron or triangle that signals expandability and rotates to indicate open versus closed. It accompanies the label and must not be the only cue that a section is toggleable.

States

Expanded versus collapsed

When a panel is visible its header button has aria-expanded=true; when hidden, aria-expanded=false. The chevron rotates to match. This state pairing is the heart of the widget: the visual and the programmatic state must always agree.

Single-open versus multi-open

In a single-open accordion, expanding a collapsed header collapses the one already open. In a multi-open accordion any combination can be open, often with open-all and close-all controls. Choose based on whether users compare sections or read them one at a time.

Animation and reduced motion

Open and close are usually animated by transitioning height and opacity. Under prefers-reduced-motion: reduce, cut or replace the slide (for example a quick fade) so the movement does not affect users sensitive to motion.

The find-on-page caveat

Content in a collapsed panel hidden with display:none cannot be found by the browser's find-in-page, and text fragments cannot link into it. The modern fix is hidden=until-found with the beforematch event, which lets the browser search hidden text and reveal the matching section.

References

The W3C APG live accordion: a Personal Information section expanded to show a form, its chevron pointing up, with collapsed Billing Address and Shipping Address headers below.
APG accordion exampleW3C WAI
The GOV.UK accordion with a Show all sections control: a Writing well for the web section expanded with a Hide toggle and its content, and collapsed sections below each with a Show toggle.
GOV.UK Design System accordionUK Government Digital Service
A native HTML details element opened: a Details summary with a downward triangle marker, revealing the line of panel text beneath it.
MDN details elementMozilla
A Material UI accordion: the Accordion 1 panel expanded with its chevron up and body text shown, and a collapsed Accordion 2 header with a downward chevron below.
Material UI accordionMUI / Material Design

Use it

Figma
An accordion item with expand/collapse variants
  1. Build one item: a vertical Auto Layout frame with a header row (label plus chevron, space-between) and a panel frame below it.
  2. Make it a component and add a State variant: Collapsed, Expanded.
  3. In Collapsed, remove the panel from the layout flow and point the chevron at rest; in Expanded, show the panel and rotate the chevron.
  4. Wire the on-click variant change with Smart Animate so the chevron rotation and panel height animate, mirroring aria-expanded flipping.

Expose the chevron as an instance swap so you can switch icon styles without rebuilding the variants.

An accordion group with an open policy
  1. Stack several item instances in a vertical Auto Layout frame: this is the grouped, labelled set.
  2. For multi-open, leave each item independent so any combination can be Expanded.
  3. For single-open, prototype selecting one item's Expanded variant resetting the others to Collapsed.
  4. Add an optional open-all and close-all row to match the GOV.UK pattern and ease the find-on-page caveat.

Keep header height and padding as shared variables so the stack stays even whether one or many panels are open.

Accessibility

An accordion is a set of headers, each a button wrapped in a heading, whose aria-expanded reports panel visibility and whose aria-controls points at the panel. All focusable elements are part of the normal page tab sequence; arrow-key navigation between headers is an optional enhancement, not a requirement, which is the opposite of the tablist's roving model.

  1. Put the button in a true heading with the correct level so the headers contribute a meaningful document outline; do not put the heading role on a div.
  2. Native <details> and <summary> are the no-JS baseline, but a real accordion needs grouping and has some assistive-tech quirks, so test it.
  3. Keep all headers in the tab order with a visible focus indicator.
  4. Honor prefers-reduced-motion by reducing or replacing the open-close animation.
  5. Account for find-in-page: collapsed panel text is unsearchable, so prefer hidden=until-found or offer open-all and close-all.
  6. The chevron must not be the only affordance; make it clear the headings are buttons.
Research notes & sources

WAI-ARIA Accordion: heading-wrapped buttons with aria-expanded and aria-controls

  1. Accordion Pattern (ARIA Authoring Practices Guide)W3C WAI
  2. Accordion Example (ARIA Authoring Practices Guide)W3C WAI
  3. Disclosure (Show/Hide) PatternW3C WAI
  4. <details>: The Details disclosure elementMDN Web Docs
  5. Disclosure Widgets
  6. Accordions for Complex Website Content on DesktopsNielsen Norman Group
  7. Accordion componentGOV.UK Design System
  8. Making collapsed content accessible with hidden=until-foundChrome for Developers (Google)
  9. prefers-reduced-motionMDN Web Docs
  10. React Accordion componentMUI (Material UI)