Skip to main content
Components

Accordion

The accordion component lets users show and hide sections of related content on a page. Without JavaScript, every section is shown.

Read the Design System guidance for accordion

Import

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

Examples

Default

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

With summary sections

Code
<Accordion.Composite
  id="accordion-with-summary-sections"
  rememberExpanded={false}
  sections={[
    {
      heading: 'Understanding agile project management',
      summary: 'Introductions, methods, core features.',
      children: list([
        'Agile and government services: an introduction',
        'Agile methods: an introduction',
        'Core principles of agile',
      ]),
    },
    {
      heading: 'Working with agile methods',
      summary: 'Workspaces, tools and techniques, user stories, planning.',
      children: list([
        'Creating an agile working environment',
        'Agile tools and techniques',
        'Set up a team wall',
        'Writing user stories',
        'Planning in agile',
        'Deciding on priorities',
        'Developing a roadmap',
      ]),
    },
  ]}
/>

Sections open

Some sections open, for visual regression.

Code
<Accordion.Composite
  id="accordion-sections-open"
  rememberExpanded={false}
  sections={headings.map((heading) => ({ heading, children: content(heading) }))}
  defaultValue={['accordion-sections-open-content-1', 'accordion-sections-open-content-3']}
/>

All open

Every section open, so the button says "Hide all sections".

Code
<Accordion.Composite
  id="accordion-all-open"
  rememberExpanded={false}
  sections={[
    {
      heading: 'Understanding agile project management',
      summary: 'Introductions, methods, core features.',
      children: list([
        'Agile and government services: an introduction',
        'Agile methods: an introduction',
        'Core principles of agile',
      ]),
    },
    {
      heading: 'Working with agile methods',
      summary: 'Workspaces, tools and techniques, user stories, planning.',
      children: list([
        'Creating an agile working environment',
        'Agile tools and techniques',
        'Set up a team wall',
        'Writing user stories',
        'Planning in agile',
        'Deciding on priorities',
        'Developing a roadmap',
      ]),
    },
  ]}
  defaultValue={['accordion-all-open-content-1', 'accordion-all-open-content-2']}
/>

With parts

Code
<Accordion.Root id="accordion-parts" rememberExpanded={false} defaultValue={['parts-1']}>
  <Accordion.Controls />
  {headings.slice(0, 2).map((heading, index) => (
    <Accordion.Section key={heading} value={`parts-${index + 1}`}>
      <Accordion.SectionHeader>
        <Accordion.SectionHeading>
          <Accordion.SectionButton id={`accordion-parts-heading-${index + 1}`}>{heading}</Accordion.SectionButton>
        </Accordion.SectionHeading>
      </Accordion.SectionHeader>
      <Accordion.SectionContent id={`accordion-parts-content-${index + 1}`}>
        {content(heading)}
      </Accordion.SectionContent>
    </Accordion.Section>
  ))}
</Accordion.Root>

Controlled

Code
<ControlledAccordion />

API reference

Accordion.Root

The accordion component lets users show and hide sections of related content on a page.

PropType
hideAllSectionsText

The text content of the 'Hide all sections' button at the top of the accordion when all sections are expanded.

string
hideSectionText

The text content of the 'Hide' button within each section of the accordion, which is visible when the section is expanded.

string
hideSectionAriaLabelText

Text made available to assistive technologies, like screen-readers, as the final part of the toggle's accessible name when the section is expanded. Defaults to "Hide this section".

string
showAllSectionsText

The text content of the 'Show all sections' button at the top of the accordion when at least one section is collapsed.

string
showSectionText

The text content of the 'Show' button within each section of the accordion, which is visible when the section is collapsed.

string
showSectionAriaLabelText

Text made available to assistive technologies, like screen-readers, as the final part of the toggle's accessible name when the section is collapsed. Defaults to "Show this section".

string
rememberExpanded

Whether the expanded/collapsed state of the accordion should be saved when a user leaves the page and restored when they return. Default is true.

boolean
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

Accordion.Composite

The accordion component lets users show and hide sections of related content on a page.

Children are SectionComposites. With sections, it fills in their ids and heading level.

PropType
defaultValue

The sections open at first.

string[]
hideAllSectionsText

The text content of the 'Hide all sections' button at the top of the accordion when all sections are expanded.

string
hideSectionText

The text content of the 'Hide' button within each section of the accordion, which is visible when the section is expanded.

string
hideSectionAriaLabelText

Text made available to assistive technologies, like screen-readers, as the final part of the toggle's accessible name when the section is expanded. Defaults to "Hide this section".

string
showAllSectionsText

The text content of the 'Show all sections' button at the top of the accordion when at least one section is collapsed.

string
showSectionText

The text content of the 'Show' button within each section of the accordion, which is visible when the section is collapsed.

string
showSectionAriaLabelText

Text made available to assistive technologies, like screen-readers, as the final part of the toggle's accessible name when the section is collapsed. Defaults to "Show this section".

string
rememberExpanded

Whether the expanded/collapsed state of the accordion should be saved when a user leaves the page and restored when they return. Default is true.

boolean
value

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

string[]
onValueChange

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

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

Heading level, from 1 to 6. Default is 2.

1 | 2 | 3 | 4 | 5 | 6
idRequired

Must be unique across the domain of your service if rememberExpanded is true (as the expanded state of individual instances of the component persists across page loads using session storage). Used as an id in the HTML for the accordion as a whole, and also as a prefix for the ids of the section contents and the buttons that open them, so that those ids can be the target of aria-control attributes.

string
sections

Prefer children, which memoise and re-render better.

Omit<SectionCompositeProps, "headingLevel" | "accordionId" | "index">[]

Accordion.Controls

The "Show all sections" button, at the top of the accordion. Hidden until JavaScript runs.

No props of its own. Other props are passed to the element it renders.

Accordion.Section

PropType
expanded

Sets whether the section should be expanded when the page loads for the first time. Defaults to false.

boolean
valueRequired

Identifies the section in the accordion's value.

string

Accordion.SectionButton

The section's heading text. Without JavaScript it's plain text. Once JavaScript runs it's a button that shows and hides the section, holding the heading and summary.

PropType
summary

The section's summary line, which the button also shows once JavaScript runs.

ReactNode

Accordion.SectionComposite

PropType
summary

The summary line of each accordion section. The summary line is inside the HTML <button> element, so you can only add phrasing content to it.

ReactNode
headingRequired

The heading of each accordion section. The header is inside the HTML <button> element, so you can only add phrasing content to it.

ReactNode
headingLevel

Heading level, from 1 to 6. Default is 2.

1 | 2 | 3 | 4 | 5 | 6
accordionIdRequired

The id of the accordion, used as a prefix for the ids of the section contents and the buttons that open them.

string
indexRequired

The section's position, from 1, used in its ids as the macro does.

number
value

Identifies the section in the accordion's value. Defaults to its content's id.

string
expanded

Sets whether the section should be expanded when the page loads for the first time. Defaults to whether the accordion's value includes it.

boolean

Accordion.SectionContent

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

No props of its own. Other props are passed to the element it renders.

Accordion.SectionHeader

No props of its own. Other props are passed to the element it renders.

Accordion.SectionHeading

PropType
headingLevel

Heading level, from 1 to 6. Default is 2.

1 | 2 | 3 | 4 | 5 | 6

Accordion.SectionSummary

The section's summary line without JavaScript. Once JavaScript runs, SectionButton shows it.

No props of its own. Other props are passed to the element it renders.