BRAID
Braid Design System
GuidesFoundationsComponentsPatternsStyles

Accordion

A vertically stacked list of panels that expand and collapse to reveal sections of content.
 
Open in Playroom

Accessibility

Follows the WAI-ARIA Disclosure Pattern.This remains the case when only one item can be open. Collapsed content stays on the page so it can animate, and is hidden from assistive technology.

Appearance

Visual prominence

You can specify the size, tone and weight props, and optionally set the dividers prop to false.
 
Open in Playroom
Deprecated

Space, deprecated

The space prop is deprecated. Spacing between items is now automatically derived from the size prop and will be removed in a future release.
 
Open in Playroom

Badges

Add an optional Badge alongside the label of the AccordionItem using the badge prop.
 
Open in Playroom

Icons

For decoration or help distinguishing between accordion items, an icon can be provided. This will be placed to the left of the label.
 
Open in Playroom

Interaction

Managing state

An AccordionItem, by default, manages its own state internally, and several items can be open at once. If you’d like to take control of an individual item, you can do so using the expanded and onToggle props. When the accordion is managing which items are open, set a value on each AccordionItem instead.
 
Open in Playroom

Single open item

If only one item should be open at a time, set multiple to false. Opening an item closes the others, and the open item can still be collapsed. Give each AccordionItem a value so the accordion can tell them apart.
 
Open in Playroom

Default value

To have an item open when the accordion first appears, set defaultValue to that item’s value. You can pass more than one value when several items should start open. If only one item can be open, pass a single value.
 
Open in Playroom

Controlled state

If you’d like to manage which items are open yourself, pass value and onChange. Give each AccordionItem a value, rather than setting expanded on the item. When multiple is false, value is a string and onChange receives a string. Use an empty string when no item is open. Otherwise they are an array of strings.
 
Open in Playroom

Best practices

Content guidelines

  • Avoid putting critical or high-priority content in an accordion, as users may not read it.
  • Label your accordion items appropriately to help users decide which sections to read.

When to use

Use an Accordion:
  • to shorten pages and reduce scrolling when content isn’t crucial to read in full (e.g. FYIs)
  • to display basic content such as text, links and occasional images.
Don’t use an Accordion:
  • if the information is needed for the user to complete their current task (make it visible upfront instead)
  • to capture complex user input, such as in a form (consider using a Drawer instead)
  • for a single section of content (consider using a Disclosure instead).

Data attributes

Braid components are very explicit about the properties they accept, which makes providing arbitrary data attributes not possible. Instead, a data prop can be provided as a single collection of data attributes.
<Accordion
  data={{ testid: 'accordion-1' }}
  // => data-testid="accordion-1"
>
  <AccordionItem
    data={{ testid: 'accordion-item-1' }}
    // => data-testid="accordion-item-1"
  >
    ...
  </AccordionItem>
</Accordion>

Alternatives

  • Dialog — For exposing additional content in a modal with rich formatting.
  • Disclosure — For revealing optional content inline with a light visual treatment.
  • Tabs — For presenting multiple sections of content in horizontal panels.
On this page