Skip to main content
Primitives

Accordion

Sections that each show and hide their content, with a control to open or close them all.

Used by govuk-react's accordion.

Unstyled

The primitive on plain elements, with no GOV.UK markup or styles: what you start from in your own library.

Code
<Accordion.Root rememberExpanded={false}>
  <Accordion.Controls>
    <Accordion.ShowAll>
      <Accordion.ShowAllText />
    </Accordion.ShowAll>
  </Accordion.Controls>
  {sections.map((section) => (
    <Accordion.Section key={section.value} value={section.value}>
      <h2>
        <Accordion.Fallback>{section.heading}</Accordion.Fallback>
        <Accordion.Trigger>
          <Accordion.Label>{section.heading}</Accordion.Label> <Accordion.ToggleText />
        </Accordion.Trigger>
      </h2>
      <Accordion.Content id={`accordion-${section.value}`}>
        <p>{section.content}</p>
      </Accordion.Content>
    </Accordion.Section>
  ))}
</Accordion.Root>

In govuk-react

govuk-react's accordion, built with this primitive.

Code
<Accordion.Composite
  id="accordion-default"
  rememberExpanded={false}
  sections={headings.map((heading) => ({ heading, children: content(heading) }))}
/>

Usage

import * as Accordion from '@govuk-react/primitives/accordion';

<Accordion.Root defaultValue={['web']}>
  <Accordion.Controls>
    <Accordion.ShowAll>
      <Accordion.ShowAllText />
    </Accordion.ShowAll>
  </Accordion.Controls>
  <Accordion.Section value="web">
    <h2>
      <Accordion.Fallback>Writing well for the web</Accordion.Fallback>
      <Accordion.Trigger>
        <Accordion.Label>Writing well for the web</Accordion.Label> <Accordion.ToggleText />
      </Accordion.Trigger>
    </h2>
    <Accordion.Content id="web-content">…</Accordion.Content>
  </Accordion.Section>
</Accordion.Root>;

Without JavaScript every section is shown under its Fallback heading. It needs the package’s stylesheet. Each section also renders a hidden Trigger with the same heading, which the element shows on upgrade while hiding the fallback. Nothing is moved, so React can keep rendering the markup. Closed content gets hidden="until-found", so find in page opens it. Labels name the trigger, followed by “Show this section” or “Hide this section”.

ShowAll opens every section, or closes them all when every one is open. value and onValueChange control the open sections once hydrated, and a section opened before hydration is reported rather than undone. As in govuk-frontend, open sections are remembered for the session by content id, unless rememberExpanded is false. In an island without a Root, pass defaultExpanded to Section.

Inline script

To make the markup interactive before React hydrates, inline @govuk-react/primitives/inline/accordion-element.js, or render it from React on the server:

import { InlineScript, accordion } from '@govuk-react/primitives/inline-script';

<InlineScript script={accordion} nonce={nonce} />;

How inline scripts work

API reference

Accordion.Root

PropType
value

The open sections' values, to control them once hydrated.

string[]
defaultValue

The sections open at first.

string[]
onValueChange

Called with the open sections' values when the user opens or closes a section.

(value: string[], details: ChangeDetails) => void
rememberExpanded

Whether to remember the open sections for the rest of the session, keyed by content id. Defaults to true, as in govuk-frontend.

boolean
showSectionText

Each button's text while its section is closed. Defaults to "Show".

string
hideSectionText

Each button's text while its section is open. Defaults to "Hide".

string
showSectionLabel

The end of each button's accessible name while its section is closed. Defaults to "Show this section".

string
hideSectionLabel

The end of each button's accessible name while its section is open. Defaults to "Hide this section".

string
showAllSectionsText

The "show all" button's text while a section is closed. Defaults to "Show all sections".

string
hideAllSectionsText

The "show all" button's text while every section is open. Defaults to "Hide all sections".

string
upgradedClass

Classes added to the element when it upgrades.

string
expandedSectionClass

Classes added to open sections.

string
collapsedIconClass

Classes added to the icons of closed sections, and the "show all" icon while a section is closed.

string

Accordion.Content

The section's content. Give it an id, which the trigger's aria-controls names.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

Accordion.Controls

Holds the "show all" button. Hidden until the element upgrades.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

Accordion.Fallback

What shows without JavaScript in place of the trigger, such as the plain heading. Hidden on upgrade.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

Accordion.Icon

An icon in a trigger or the "show all" button, given collapsedIconClass while closed.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

Accordion.Label

Text in the trigger that names it, such as the heading or summary.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

Accordion.Section

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean
valueRequiredstring
defaultExpanded

Whether it's open at first. Defaults to whether Root's value includes it.

boolean

Accordion.ShowAll

Shows every section, or hides every section when all are open.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

Accordion.ShowAllText

The "show all" button's text, which the element sets.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

Accordion.ToggleText

The trigger's show or hide text, which the element sets.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

Accordion.Trigger

The button that shows and hides its section. Hidden until the element upgrades.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean