Skip to main content

Accordion

Expandable and collapsible content panels built on the native <details> and <summary> elements. Panels that share a name attribute form an exclusive group (only one open at a time); without a shared name each panel opens independently. The accordion works without JavaScript, with optional JS progressive enhancement for expand/collapse-all controls.

Usage​

When to use

  • Grouping related chunks of secondary content under headings a user can open on demand
  • Reducing page length on long reference pages (FAQ, documentation, product details)
  • Progressive disclosure where full content is not critical on first view

When not to use

  • For primary page content that every user needs to read - do not hide it behind a toggle
  • For navigation between pages - use a navigation component
  • When only a single panel is needed - use a simple collapsible instead

Do

  • Write descriptive triggers so users know what is inside before expanding
  • Use exclusive mode when panels are alternative views of the same topic
  • Keep panel content short and scannable

Don't

  • Nest accordions inside accordions
  • Hide error messages, validation feedback, or required form steps inside a collapsed panel
  • Rely on color alone to indicate open/closed state - use the chevron and native expanded state

API​

Props​

PropTypeDefaultDescription
itemsarray-Array of {title, content, name, is_open} panel objects. title is the collapsed summary; content is the expanded body; name groups panels for exclusive-open behavior; is_open pre-expands the panel.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.subtleEmphasis-Lower emphasis; a muted, quieter weight.
.neutralEmphasisYesDefault emphasis; the standard weight at balanced contrast.
.accentEmphasis-Higher emphasis; a stronger, louder weight.
.solidFill-Filled surface; background and border rendered.
.outlineFill-Bordered surface; transparent background.
.ghostFill-No surface; text or icon only.
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.fluidLayout-Full-width, no max-width.
.containedLayoutYesConstrained to a max-width.
.animatedMotionYesHonors the animations option.
.stillMotion-Forces motion off regardless of the option.
.flatElevationYesNo elevation.
.raisedElevation-Slight elevation.
.flushSpacing-No separation; the parts meet directly.

Attributes​

AttributeSet byRequiredDescription
data-collapsibleConsumerYesMarks a collapsible root; the utility resolves the trigger and panel and wires the toggle behavior.
data-collapsible-triggerConsumer-Identifies the trigger element when the default first-child rule does not fit.
data-collapsible-panelConsumer-Identifies the panel element when the default second-child rule does not fit.
data-collapsible-trigger-no-iconConsumer-Opts a trigger out of automatic chevron injection.
data-collapsible-trigger-wideConsumer-Selects the wider chevron variant for the injected icon.
data-collapsible-durationConsumer-Animation duration in milliseconds; 0 (or prefers-reduced-motion) skips the animation.
data-collapsible-groupConsumer-Group name; opening one collapsible in a group collapses the rest, like an accordion.
data-collapsible-group-enabled-breakpointConsumer-Minimum viewport width (px) at which the mutual-exclusion group is active; below it each collapsible toggles independently.
data-collapsible-collapsedScript-Present on a root while its panel is closed; reflects ARIA state, toggled on every expand / collapse.
data-collapsible-collapsingScript-Present on a root while the expand / collapse animation is running; cleared on transitionend.
data-collapsible-wrapperScript-Marks the synthetic wrapper the utility inserts inside a multi-child <details> to animate the non-summary children as one panel.
data-collapsible-animatingScript-Present on the panel while an expand / collapse animation runs; the panel CSS keys its overflow, box-sizing, height and transition off it.
data-collapsible-closedScript-Present on the panel while it renders closed geometry, both the resting collapsed state and the zero endpoint of an animation; the panel CSS keys display and the zeroed block metrics off it.

Events​

EventDirectionDescription
collapsible-expandedEmitsFired on the root after it expands.
collapsible-collapsedEmitsFired on the root after it collapses.
collapsible-toggledEmitsFired on the root after any state change, so a listener can handle both transitions in one place.
collapsible-expandListensProgrammatic expand request (no detail): opens the panel if it is currently closed.
collapsible-collapseListensProgrammatic collapse request (no detail): closes the panel if it is currently open.

Examples​

Independent​

Default accordion where any number of panels can be open at once.

Exclusive​

One-at-a-time behavior using the shared name attribute on each <details> element.

Flush​

Edge-to-edge variant with no outer border, for embedding inside cards or content regions.

Still​

Motion set to still, which holds the panel height, the summary color and the chevron rotation at zero duration. The panels open and close instantly.

Collapsible​

Accordion with data-collapsible set, deferring panel animation to the collapsible utility's JS-driven transition instead of the CSS-only default.

Expand all​

Accordion with an expand-all / collapse-all control above the list.

Accessibility​

  • WCAG 2.2 AA
  • Full keyboard support: the trigger can be reached with Tab and activated with Enter or Space.
  • Expanded/collapsed state is announced by assistive tech.
  • Visible focus ring on the trigger
  • Expand-all / collapse-all state changes are announced politely.
  • Chevron animation respects prefers-reduced-motion.
  • Supports find-in-page via hidden="until-found" so collapsed content is discoverable by browser search

Progressive enhancement​

  • No JS: native <details> / <summary> handles open/close, keyboard, and aria-expanded automatically. Independent mode works out of the box.
  • With JS: adds exclusive mode coordination across panels and the expand-all / collapse-all control with a live-region status announcement
  • How to enable: include the accordion JS enhancement; set a shared name attribute on <details> elements for exclusive mode
  • collapsible - single-panel reveal behavior without the list structure