Skip to content

Accordion

C-15 · Components · Navigation

All elements · Accordion on the Components page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for Accordion.

Accordion

C-15WCAG 2.2 AA · Passed #408

Native <details>/<summary>. Exclusive open uses the name attribute.

Axis Values
data-variant default · separated · flush
name same name on every item = exclusive
Default (exclusive) and separated
General
Name, type and description fields live here.
Permissions
Operator groups and access rules.
History
Audit trail.
Separated item
Each item is its own card.
Another item
Content.

Guidance

When to use

  • Group a long settings or properties form into sections the user opens one at a time.
  • Hide secondary detail, such as History or Permissions, below the main content of a pane.
  • Make sections exclusive, so opening one closes the others, by giving every item the same name.
  • Show sections as separate cards with data-variant="separated", or edge to edge in a pane with data-variant="flush".

When to consider something else

  • When the sections are peer views and only one should show, use Tabs. See Tabs.
  • When the content is a deep hierarchy of items, not a few sections, use Tree. See Tree.
  • When most users need most sections, show them all on the page and skip the accordion.
  • When one extra detail sits next to a control, use Popover or Tooltip instead of a whole section. See Popover.

Usability

Do
  • Write titles that say what is inside, such as Permissions, not More.
  • Open the first section, or the one holding an error, by default with open.
  • Open a closed section automatically when it holds a validation error and move focus to the error.
  • Keep each section short; if a section needs its own scroll, it should be a separate pane or page.
Don’t
  • Don't put the only Save button inside a section that can be closed.
  • Don't nest accordions more than one level deep.
  • Don't use exclusive mode when users need to compare two sections.

Accessibility

Keyboard

Accordion keyboard
Keys Action
Tab / Shift+Tab Moves between section headers and into open content.
Enter or Space Opens or closes the focused section (native summary behavior).

Roles and names

  • Each item is a native <details class="qf-accordion__item"> with a <summary class="qf-accordion__trigger">; the browser exposes the expanded state, so no aria-expanded is added.
  • The leading icon and the chevron are decorative and carry aria-hidden="true"; the name comes from .qf-accordion__title.
  • When sections are page structure, wrap the title in a heading at the right level inside the summary, so heading navigation finds them.
  • Exclusive open uses the native name attribute; no script is needed.

Focus

  • Every summary is one Tab stop in document order; closed content is skipped.
  • The trigger shows the shared focus ring (.qf-accordion__trigger:focus-visible).
  • Opening a section does not move focus; focus stays on the trigger.

Other requirements

  • Triggers are at least 3rem high, which meets 2.5.8.
  • The chevron rotation is the only motion and is removed under prefers-reduced-motion (2.3.3).
  • Content found by in-page search opens closed details in supporting browsers; do not block that with script.
  • The chevron direction must not be the only state cue to sighted users; keep the open content visible below the trigger (1.4.1).

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

Accordion test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order. (2 rows)
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (4 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- accordion --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

Accordion package
Source css/classic/components/navigation.css
Specimens also use Box · Card · Chip · Icon · Table · Text · Toolbar
Sprites sprites/icons.svg
React Not yet available: the React binding has not started.

Latest updates

No recorded changes yet.

All release notes