Accordions

Last updated:

Practical patterns for progressive disclosure with native markup and accessible keyboard behaviour.

01 — Foundation

Reveal content progressively

Accordions reduce scanning load when used carefully — not when they bury essential information.

Accordions group related content into expandable sections. Used well, they support compact layouts and optional detail. Used badly, they turn pages into hidden-content archaeology.

02 — When

When accordions help — and when they do not

Accordions should reduce complexity, not hide what users need to see.

Good fits

  • FAQs, documentation sections, and optional supporting detail
  • secondary information on mobile where space is tight

Poor fits

  • essential pricing, warnings, or steps users must see without clicking
  • deeply nested accordions or entire pages collapsed by default

03 — Markup

Use the platform first

Native disclosure with buttons beats div click handlers.

<details>
    <summary>Shipping and returns</summary>
    <p>Standard delivery is 3–5 working days. Returns accepted within 30 days.</p>
</details>

<details>
    <summary>Warranty</summary>
    <p>Two-year warranty on manufacturing defects.</p>
</details>

For custom accordion sets, use real buttons with clear expanded state — not generic divs with click handlers.

04 — Accessibility

Keyboard, state, and motion

Users should know what opens, what is expanded, and how to move predictably.

  • full keyboard support — expand, collapse, and move between sections
  • expanded state exposed to assistive technology
  • restrained animation; respect prefers-reduced-motion

05 — Review

Before you approve

A short checklist for accordions in code review.

  • critical content is visible without opening every section
  • semantic buttons or details / summary
  • keyboard and screen reader behaviour tested
  • a simpler open layout would not serve users better

If users must open every accordion to understand the page, the accordion is failing.