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
| Guidance | Practice |
|---|---|
| Do | Put each Accordion.Trigger inside an Accordion.Header, so the trigger sits in a heading. |
| Do | Animate the panel height with --cl-accordion-panel-height, set from the measured panel. |
| Don’t | Pass id to a trigger or panel. The primitive owns both to pair them. |
| Don’t | Use 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.
| Prop | Type | Description |
|---|---|---|
value | string[] | The open item values, when controlled. |
defaultValue | string[] | The open item values on mount, when uncontrolled.Default: [] |
onValueChange | (value: string[]) => void | Called with the new open item values. |
type | 'single' | 'multiple' | single keeps at most one item open.Default: 'multiple' |
disabled | boolean | Disables every item.Default: false |
Accordion.Item
One section. Carries data-open or data-closed, and data-disabled.
| Prop | Type | Description |
|---|---|---|
value | string | Identifies the item in value. Unique within the root. |
disabled | boolean | Disables 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
<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>