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
| Prop | Type | Default | Description |
|---|---|---|---|
items | array | - | 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. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.subtle | Emphasis | - | Lower emphasis; a muted, quieter weight. |
.neutral | Emphasis | Yes | Default emphasis; the standard weight at balanced contrast. |
.accent | Emphasis | - | Higher emphasis; a stronger, louder weight. |
.solid | Fill | - | Filled surface; background and border rendered. |
.outline | Fill | - | Bordered surface; transparent background. |
.ghost | Fill | - | No surface; text or icon only. |
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.fluid | Layout | - | Full-width, no max-width. |
.contained | Layout | Yes | Constrained to a max-width. |
.animated | Motion | Yes | Honors the animations option. |
.still | Motion | - | Forces motion off regardless of the option. |
.flat | Elevation | Yes | No elevation. |
.raised | Elevation | - | Slight elevation. |
.flush | Spacing | - | No separation; the parts meet directly. |
Attributes
| Attribute | Set by | Required | Description |
|---|---|---|---|
data-collapsible | Consumer | Yes | Marks a collapsible root; the utility resolves the trigger and panel and wires the toggle behavior. |
data-collapsible-trigger | Consumer | - | Identifies the trigger element when the default first-child rule does not fit. |
data-collapsible-panel | Consumer | - | Identifies the panel element when the default second-child rule does not fit. |
data-collapsible-trigger-no-icon | Consumer | - | Opts a trigger out of automatic chevron injection. |
data-collapsible-trigger-wide | Consumer | - | Selects the wider chevron variant for the injected icon. |
data-collapsible-duration | Consumer | - | Animation duration in milliseconds; 0 (or prefers-reduced-motion) skips the animation. |
data-collapsible-group | Consumer | - | Group name; opening one collapsible in a group collapses the rest, like an accordion. |
data-collapsible-group-enabled-breakpoint | Consumer | - | Minimum viewport width (px) at which the mutual-exclusion group is active; below it each collapsible toggles independently. |
data-collapsible-collapsed | Script | - | Present on a root while its panel is closed; reflects ARIA state, toggled on every expand / collapse. |
data-collapsible-collapsing | Script | - | Present on a root while the expand / collapse animation is running; cleared on transitionend. |
data-collapsible-wrapper | Script | - | Marks the synthetic wrapper the utility inserts inside a multi-child <details> to animate the non-summary children as one panel. |
data-collapsible-animating | Script | - | 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-closed | Script | - | 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
| Event | Direction | Description |
|---|---|---|
collapsible-expanded | Emits | Fired on the root after it expands. |
collapsible-collapsed | Emits | Fired on the root after it collapses. |
collapsible-toggled | Emits | Fired on the root after any state change, so a listener can handle both transitions in one place. |
collapsible-expand | Listens | Programmatic expand request (no detail): opens the panel if it is currently closed. |
collapsible-collapse | Listens | Programmatic 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, andaria-expandedautomatically. 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
nameattribute on<details>elements for exclusive mode
Related
- collapsible - single-panel reveal behavior without the list structure