Skip to content
Mosaic
On this page

Accordion

Headless, unstyled stack of collapsible sections, with one or many open at once. Wires aria-expanded, aria-controls and role="region", and moves focus between triggers with the arrow keys.

Use for

  • a set of sections that each show and hide their content
  • a FAQ or a settings list with expandable rows

Practices

GuidancePractice
DoPut each Accordion.Trigger inside an Accordion.Header, so the trigger sits in a heading.
DoAnimate the panel height with --cl-accordion-panel-height, set from the measured panel.
Don’tPass id to a trigger or panel. The primitive owns both to pair them.
Don’tUse it for a single show-and-hide section. Use Collapsible instead.

API reference

Accordion.Root

Holds which items are open and the arrow-key navigation across triggers. Renders a div, or the render element.

PropTypeDescription
valuestring[]The open item values, when controlled.
defaultValuestring[]The open item values on mount, when uncontrolled.Default: []
onValueChange(value: string[]) => voidCalled with the new open item values.
type'single' | 'multiple'single keeps at most one item open.Default: 'multiple'
disabledbooleanDisables every item.Default: false

Accordion.Item

One section. Carries data-open or data-closed, and data-disabled.

PropTypeDescription
valuestringIdentifies the item in value. Unique within the root.
disabledbooleanDisables this item.Default: the root's `disabled`

Accordion.Header

Renders an h3 around the trigger.

Accordion.Trigger

A button that toggles its item. Carries aria-expanded and aria-controls, and the same data attributes as the item.

Accordion.Panel

The content, as role="region" labelled by its trigger. Unmounts once closed and its exit transition ends.

Examples

One open at a time

TSX
<Accordion.Root type='single' defaultValue={['billing']}>
  <Accordion.Item value='billing'>
    <Accordion.Header>
      <Accordion.Trigger>Billing</Accordion.Trigger>
    </Accordion.Header>
    <Accordion.Panel>…</Accordion.Panel>
  </Accordion.Item>
</Accordion.Root>