canon-accordion

CANON · Accordions

An accordion is a disclosure widget — a heading that toggles content visibility. Useful in moderation. Often overused to hide things that should just be visible.

When to use an accordion

Appropriate	Not appropriate
FAQ sections	Primary content users need to see
Optional settings users don't always expand	Forms (users miss fields they didn't open)
Long reference content organized into topics	Short content that fits on the page
Dense lists where each row has rich drill-down detail	Hiding critical errors or confirmations

Don't use accordions to hide information users actually need. If the content matters, show it.

Use <details> / <summary> when possible

Native HTML gives you keyboard, screen reader, toggle state, and animation primitives for free.

<details>
  <summary>What's your return policy?</summary>
  <p>Returns accepted within 30 days of purchase. Items must be unused.</p>
</details>

• Enter / Space on <summary> toggles.
• Keyboard focus works natively.
• Screen readers announce expanded/collapsed.
• Default disclosure triangle can be styled or replaced.
• Use CSS details[open] to animate.

Reach for custom ARIA only when native doesn't fit — e.g., controlling multiple sections with complex behavior.

Custom ARIA pattern

When <details> won't do:

<h3>
  <button
    aria-expanded="false"
    aria-controls="panel-1"
    id="trigger-1"
  >
    What's your return policy?
    <svg aria-hidden="true">▼</svg>
  </button>
</h3>

<div
  id="panel-1"
  role="region"
  aria-labelledby="trigger-1"
  hidden
>
  <p>Returns accepted within 30 days.</p>
</div>

• Button wraps the heading text (not the heading itself).
• Heading element (<h3> etc.) wraps the button to preserve document outline.
• aria-expanded toggles true/false.
• aria-controls points to panel id.
• Panel has role="region" and aria-labelledby.
• Hide with hidden attribute (or display: none), not visibility: hidden.