Accordion

Preview

When to use

Use an accordion to progressively disclose content that is supplementary or optional. It works well for:

• FAQ sections where users scan questions and only open what's relevant.
• Settings or filter panels where the full list would overwhelm the view.
• Product detail pages where secondary information (care instructions, specifications) doesn't need to be visible by default.

When not to use

• When most users need all the content — a plain page section is clearer than forcing users to click.
• To hide critical information or primary calls to action. If the user must see it, show it.
• For a single expandable item — a simple disclosure element is more appropriate.
• When content sections must be read in order — a step-by-step layout is better.

Behaviour

Clicking or activating the title row toggles the panel open or closed. The entire title row is interactive — not just the chevron icon.

In a group, multiple accordions can be open at the same time. Interactive elements inside a panel (links, buttons, form fields) are only reachable when the panel is expanded.

Anatomy

• Title row — the clickable trigger. Contains the chevron icon and the accordion title text.
• Chevron icon — indicates state. Points downward when collapsed; rotates upward when expanded.
• Panel — the expandable content area below the title row. Can contain text, components, or a slot for custom content.
• Focus ring — appears around the title row when navigated via keyboard.

Variants

• Block — each accordion sits inside a rounded, bordered card with an elevated background. Use on surfaces where visual separation from the background matters.
• Divider — accordions are separated by horizontal lines without a card container. Use for inline content sections within a page.
• Quiet — minimal styling with only top and bottom borders. The lowest visual weight; use when the accordion should sit flush with surrounding content.
• Accordion group — multiple accordions stacked vertically with consistent spacing. All three style variants support grouping.

States

• Default — collapsed; title row is visible, panel is hidden.
• Hover — title row surface highlights when the cursor is over it.
• Focus — a focus ring is visible on the title row when navigated via keyboard.
• Expanded — panel is open below the title row; chevron rotates to point upward.
• Disabled — the accordion is non-interactive and visually reduced.
• Error — signals that a section (e.g. a form group inside the panel) contains an error.
• Loading — content inside the panel is being fetched or rendered.

Placement & layout

Accordions span the full width of their container. In a group, they stack vertically.

• Use the Block variant on elevated surfaces like cards or dialogs.
• Use Divider or Quiet for accordions embedded in page sections.
• Avoid lists of more than roughly 15–20 items; consider filtering or pagination instead.

Accessibility

Keyboard navigation

• Tab / Shift+Tab — move focus between accordion headers.
• Enter or Space — expand or collapse the focused accordion.
• Down Arrow / Up Arrow (optional) — move focus to the next or previous accordion header.
• Home / End (optional) — move focus to the first or last accordion header.

Screen reader support

• The title row uses role="button" with aria-expanded to announce expanded/collapsed state.
• Panels use aria-labelledby to reference their header.
• aria-controls links the header to its corresponding panel ID.
• State changes are announced automatically when toggled.

Related components

• Dialog — for content that requires immediate attention in an overlay, rather than inline disclosure.
• Fly-in — for supplementary content that slides in from the side at a page level.
• Notification — for communicating error or status messages that should always be visible, not hidden in a panel.