Accordion

Long content that people scan first and read selectively — an FAQ, a settings page of grouped preferences, terms and policy sections, a stack of records where each header carries the summary and the panel carries the detail. Also when sections need group-level machinery: expand/collapse all, a completion read-out, a cap on how many stay open, or an open set that survives a page visit.

Accordion is a stack of disclosure sections — a header you can scan and a panel you open — for content that is genuinely long: an FAQ, a settings page, a batch of records each with detail underneath. It is the WAI-ARIA Accordion pattern, so Radix keeps the parts that must be exactly right (the arrow-key roving model, aria-expanded / aria-controls, single-versus-multiple state) and garn supplies the design-system surface on top.

The structural idea worth knowing is that the header is a row, not a button. AccordionTrigger always renders its own heading around the button, at the level headingLevel names — so the document outline is real, and a nested accordion inherits its host's level plus one automatically. Compose an AccordionHeader around it and you get a layout row instead: the heading, then AccordionActions (a link, a switch, a menu, a status badge), then the caret as the row's trailing mark. Because the actions live beside the button rather than inside it, they stay out of its accessible name, they're reachable by Tab, and using one doesn't toggle the panel. That single split is what lets a collapsed row answer most of the question — a title, a summary line of counts and timestamps, a status badge, and a row action — before anyone opens anything.

The row's interaction model is one model across both layouts: the whole row tints edge-to-edge whenever a toggle affordance is hovered (the trigger, or the redundant caret beside it), the caret carries its own slightly darker square on top, and nothing moves on press.

Beyond the look axes, the depth is in the state handling. Sections take a status tone (a soft tint, an accent rail that stretches as the panel opens, and a glyph paired with hidden text — never colour alone) and a loading flag. Panels mount lazily by default, so a never-opened panel costs nothing; keepMounted or mount="eager" opts a panel back in when its form state, its find-in-page text, or a chart's measurement needs to exist. persistKey restores the open set from sessionStorage before paint, and maxOpen caps how many sections stay open at once, closing the least-recently-opened one — never one holding focus — and announcing it. AccordionToggleAll, AccordionProgress and AccordionSkeleton are group-level parts that read the same registry the sections write to, so none of them can drift from the stack.

Reach for an accordion only when the content is genuinely long. Collapsing a handful of short items adds clicks for no gain — show them outright. It earns its keep when the natural flow is scan the headers, then open one.

Choose single vs multiple deliberately. single collapsible keeps the page tidy and the focus on one section; multiple lets people compare sections side by side. If multiple risks a wall of open panels, cap it with maxOpen rather than trusting restraint.

Set headingLevel to match the page. The default 3 suits a section under an h2. State it once at the top — nested accordions step down on their own.

Make the collapsed row do work. A short parallel title, a summary line carrying the counts or timestamp people are actually after, and a status tone or badge — so the stack is scannable shut. Front-load the keyword.

Put anything interactive in AccordionActions, never in the trigger. A button inside a button is invalid, and it would join the toggle's accessible name. Actions require an explicit AccordionHeader.

Don't hide essentials. A required form field or a critical warning inside a collapsed panel may never be read. If it must be found by browser search or printed, switch that panel to keepMounted (or the root to mount="eager") — lazy panels are genuinely absent from the DOM.

Style through the axes. appearance and size drive surface and density for the whole stack from the root; don't hand-pad a row or restyle the parts to fake a rung.