Skip to main content
On this page

Accordion

Accordions let users show and hide sections of related content on a page.

When to use​

  • To show an overview of multiple related sections of content, where users can selectively reveal what is relevant to them
  • To let users compare details across sections without having to navigate away
  • For frequently-asked-question lists where most users will not read every answer
  • When page length would otherwise be very long and most content is optional for any given user

When not to use​

  • When the content is essential and all users must see it - place the content directly on the page as body text instead. Hiding critical information risks users missing it.
  • For a sequence of questions - use a separate page per question in a multi-step form, following the one-thing-per-page pattern.
  • For content that belongs in a navigation structure - use Tabs instead.
  • For a single show/hide toggle - use Disclosure instead, which is lighter and does not carry the visual weight of a full accordion group.
  • When you need to nest accordions - do not nest accordions inside other accordions. Flatten the content hierarchy instead.

Anatomy​

  1. Container (the Card wrapper that groups all accordion items)
  2. Header (the clickable area containing the button and title)
  3. Toggle button (the button that expands or collapses the panel; contains the icon and title text)
  4. Icon (plus when collapsed, minus when expanded)
  5. Title (the label for the section)
  6. Content panel (the region revealed when the accordion is expanded; hidden from all users when collapsed)

Keyboard support​

Keyboard functions​

  • Enter / Space: toggle the focused accordion open or closed
  • Tab: move focus to the next focusable element inside the content panel (when expanded) or to the next accordion header

Basic usage​

Loading...
Edit live code
<AccordionGroup>
    <Accordion title="Where does my carbon footprint come from?">
        <P>Good question. As you might have guessed from the examples above, your carbon footprint comes from many areas. Like driving your car. How you power your home. Which foods you decide to eat.</P>
    </Accordion>
    <Accordion title="How do I calculate my carbon footprint?">
        <P>To calculate it, you have to add up the carbon emitted by absolutely everything you do, over time. We take you through the things you'd need to look at below.</P>
        <P>The average carbon footprint of a person in the UK weighs in at 6.6 tonnes. Sounds like quite a lot, doesn't it. Yikes.</P>
    </Accordion>
</AccordionGroup>

Variants and features​

Default expanded​

Accordions are collapsed by default. Pass expanded to open a panel on initial render. This is useful when you want to draw attention to a specific section on page load.

Loading...
Edit live code
<AccordionGroup>
  <Accordion expanded title="Where does my carbon footprint come from?">
    <P>Good question. As you might have guessed from the examples above, your carbon footprint comes from many areas. Like driving your car. How you power your home. Which foods you decide to eat.</P>
  </Accordion>
  <Accordion title="How do I calculate my carbon footprint?">
    <P>To calculate it, you have to add up the carbon emitted by absolutely everything you do, over time. We take you through the things you'd need to look at below.</P>
    <P>The average carbon footprint of a person in the UK weighs in at 6.6 tonnes. Sounds like quite a lot, doesn't it. Yikes.</P>
  </Accordion>
</AccordionGroup>

Custom heading level​

The accordion title renders as an h3 by default. You must use headingComponent to match the heading level to the document outline of the page it sits on.

Loading...
Edit live code
<AccordionGroup>
  <Accordion headingComponent={Heading4} title="Where does my carbon footprint come from?">
    <P>Good question. As you might have guessed from the examples above, your carbon footprint comes from many areas. Like driving your car. How you power your home. Which foods you decide to eat.</P>
  </Accordion>
  <Accordion headingComponent={Heading4} title="How do I calculate my carbon footprint?">
    <P>To calculate it, you have to add up the carbon emitted by absolutely everything you do, over time. We take you through the things you'd need to look at below.</P>
    <P>The average carbon footprint of a person in the UK weighs in at 6.6 tonnes. Sounds like quite a lot, doesn't it. Yikes.</P>
  </Accordion>
</AccordionGroup>

Controlled toggle​

Use onToggle to respond to open/close events, for example to track analytics or to synchronise state elsewhere in the page.

onToggle does not control the panel: the accordion still manages its own open state.

Loading...
Edit live code
() => { // ignore - for live code example only.
  const Example = () => {
    const [lastToggled, setLastToggled] = useState('nothing yet');

    return (
      <Stack spaceBetween={3}>
        <AccordionGroup>
          <Accordion
            title="Where does my carbon footprint come from?"
            onToggle={() => setLastToggled('Where does my carbon footprint come from?')}
          >
            <P>Good question. As you might have guessed from the examples above, your carbon footprint comes from many areas. Like driving your car. How you power your home. Which foods you decide to eat.</P>
          </Accordion>
          <Accordion
            title="How do I calculate my carbon footprint?"
            onToggle={() => setLastToggled('How do I calculate my carbon footprint?')}
          >
            <P>To calculate it, you have to add up the carbon emitted by absolutely everything you do, over time. We take you through the things you'd need to look at below.</P>
          </Accordion>
        </AccordionGroup>
        <P>Last toggled: {lastToggled}</P>
      </Stack>
    );
  }

  return <Example />;
}

Grouping​

Wrap related accordion items in AccordionGroup. The group provides the Card container and the dividers between items.

Do not place a single accordion item outside an AccordionGroup unless you have a strong reason. A lone accordion without its group container loses the visual structure that helps users understand the pattern.