Accordion

The <Accordion /> component allows a user to gain a quick overview of information via the header, which they can click to expand or collapse the additional details beneath.

Show codeCopy code

It is important to consider the heading structure of your whole page when adding an <Accordion /> or <AccordionGroup />. The heading in your accordion should fall logically within the page's heading hierarchy to help assistive technology users navigate the page. By default, the titleHeadingLevel prop is set to 2, rendering a <h2> as the HTML element for the heading with the style of a <h6>. You can adjust this level via the titleHeadingLevel prop by setting it to 2, 3, 4, 5 or 6. NOTE: This won't change the styles, just the HTML element.

Show codeCopy code

By default, the accordion is collapsed but can be expanded on load by passing the expanded prop with the value of true.

Show codeCopy code

There are two options for weight: bold (default) and subtle. It's best to keep weights the same across each Accordion in the same group. This provides consistency and the best user experience.

The bold weight is best for pages with ample space and at large screen sizes.

Show codeCopy code

subtle weight is best used when space is constricted, e.g. in a card, tile, modal or side panel.

Show codeCopy code

Spacing around the title text and details can be controlled by the density prop. Consistency across each Accordion in a group is important for readability, as with the weight.

Show codeCopy code

Show codeCopy code

Show codeCopy code

By default the expand indicator (chevron) is placed on the right side of the header. The alignExpandIndicator prop allows for the title on the left side to vertically align with other element titles in the layout. Aligning the indicator to the left can be useful in large layouts where it may get overlooked, given the distance the user's eye needs to travel.

Show codeCopy code

Show codeCopy code

The items prop allows you to add interactive or static content to the end of the accordion header. It accepts an array of objects, each specifying the type of element to display and its associated properties.

Show codeCopy code

The customHeader prop has been deprecated and will be removed in the next major version. Instead, use the items prop for a structured and accessible way to add interactive or static content to the accordion header.

Previously, the customHeader prop accepted a function that returned a custom component. This was primarily used to add action buttons to the accordion header.

<Accordion
  customHeader={() => (
    <Flex justifyContent="space-between" alignItems="center" width="100%">
      {/* Emulate default text styles for the accordion header */}
      <Text color="neutralBold" fontFamily="sans" fontSize="standard" fontWeight="bold" lineHeight="tight">
        A custom header
      </Text>
      {/* Custom button */}
      <Button label="Header action" onClick={console.info} size="small" />
    </Flex>
  )}
>
  Accordion details
</Accordion>

Now, instead of providing a function, pass an array to the items prop. This supports button, actionsDropdown, or node for custom components.

<Accordion
  title="A custom header"
  items={[
    {
      type: 'button',
      label: 'Header action',
      onClick: console.info,
      size: 'small',
    },
  ]}
>
  Accordion details
</Accordion>

To consistently group a set of accordions, you can use the <AccordionGroup /> component. This will stack the accordions with consistent spacing. You can also make the group discoverable as a landmark by screen readers by passing in an ariaLabel. It's important to keep the density, weight and alignExpandIndicator values consistent across each accordion in the group.

Show codeCopy code