name: Accordion (experimental) description: The accordion component lets users show and hide sections of related content on a page. govuk_frontend_components: - accordion body: | This component is based on the [design system accordion component](https://design-system.service.gov.uk/components/accordion/) and is currently experimental because more research is needed to validate it. If using this component, [please feed back any research findings to the Design System team](https://design-system.service.gov.uk/components/accordion/#next-steps). accessibility_criteria: | The accordion must: * accept focus * be usable with a keyboard * the controls must change in appearance when keyboard focus moves to it * the controls must indicate when the mouse is hovered over it * be usable with touch * be usable with voice commands * have visible text * indicate to users that each section can be expanded and collapsed * inform the user when a step has been expanded or collapsed * be readable when only the [text of the page is zoomed in](https://support.mozilla.org/en-US/kb/font-size-and-zoom-increase-size-of-web-pages#w_how-to-only-change-the-size-of-the-text) * zoom in up to 300% without the text spilling off the screen * pass colour contrast * the accordion header button element has aria-controls set to the ID of the element containing the accordion panel content. * section content must have aria-label / aria-labelledby with a value that refers to the button that controls display of the content. Section headings must use a button element: * so that sections can be toggled with the space and enter keys * so that sections can't be opened in a new tab or window When JavaScript is unavailable the component must: * be fully expanded * not be marked as expandable shared_accessibility_criteria: - link examples: default: data: items: - heading: text: Writing well for the web content: html:
This is the content for Writing well for the web.
- heading: text: Writing well for specialists content: html:This is the content for Writing well for specialists.
- heading: text: Know your audience content: html:This is the content for Know your audience.
- heading: text: How people read content: html:This is the content for How people read.
with_supplied_identification: description: | An `id` is optional as it's automatically generated, but it can be supplied if a specific `id` is required. The `id` must be **unique** across the domain of your service - this is because as the open / closed state of individual instances of the accordion persists across page loads using `localStorage`. Used as an `id` in the HTML for the accordion as a whole, and also as a prefix for the `id`s of the section contents and the buttons that open them, so that those `id`s can be the target of `aria-labelledby` and `aria-control` attributes. data: id: with-supplied-id-thats-unique-across-the-domain items: - heading: text: Writing well for the web content: html:This is the content for Writing well for the web.
- heading: text: Writing well for specialists content: html:This is the content for Writing well for specialists.
- heading: text: Know your audience content: html:This is the content for Know your audience.
- heading: text: How people read content: html:This is the content for How people read.
with_summary: description: Adds a subheading below each section heading. data: items: - heading: text: Understanding agile project management summary: text: Introductions, methods, core features. content: html: 'This is the content for Writing well for the web.
data_attributes: gtm: gtm-accordion-item-1 - heading: text: Writing well for specialists content: html:This is the content for Writing well for specialists.
data_attributes: gtm: gtm-accordion-item-2 - heading: text: Know your audience content: html:This is the content for Know your audience.
data_attributes: gtm: gtm-accordion-item-3 - heading: text: How people read content: html:This is the content for How people read.
data_attributes: gtm: gtm-accordion-item-4 different_heading_level: description: This will alter the level of the heading, not the appearance of the heading. data: heading_level: 3 items: - heading: text: Writing well for the web content: html:This is the content for Writing well for the web.
- heading: text: Writing well for specialists content: html:This is the content for Writing well for specialists.
- heading: text: Know your audience content: html:This is the content for Know your audience.
- heading: text: How people read content: html:This is the content for How people read.
with_margin_bottom: description: | The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having a margin bottom of 30px. data: margin_bottom: 0 items: - heading: text: Writing well for the web content: html:This is the content for Writing well for the web.
- heading: text: Writing well for specialists content: html:This is the content for Writing well for specialists.
with_section_open: description: | Adding `expanded: true` to the item will mean the section will default to being open, rather than closed. Once a user has opened or closed a section, the state of each section will be remembered - this can override a section's default. data: items: - heading: text: Writing well for the web content: html:This is the content for Writing well for the web.
expanded: true - heading: text: Writing well for specialists content: html:This is the content for Writing well for specialists.
- heading: text: Know your audience content: html:This is the content for Know your audience.
- heading: text: How people read content: html:This is the content for How people read.
with_the_anchor_link_navigation: description: | Some apps require custom ids per accordion section heading for linking between those specific sections, sometimes across multiple pages. An example of this is on manuals pages where multiple manuals will each include large sets of accordions and will reference between specific sections for ease of access to that content. [Live example](https://www.gov.uk/guidance/how-to-publish-on-gov-uk/creating-and-updating-pages#associations). This feature automatically opens accordions when an anchor link is clicked within another accordion that links to either the id of an accordion section heading or an id within the content of an accordion. This will also automatically navigate to and open accordions on page load using the same rules. This feature won't be used if the `anchor_navigation` flag isn't passed as true to mitigate performance risk from event listeners on a large number of links. Unlike with the accordion-wide custom id attribute, any ids passed to accordion headings as part of this feature aren't stored in `localStorage` so don't need to be unique across your domain, but **should still be unique in the context of the page**. data: anchor_navigation: true items: - heading: text: Writing well for the web id: writing-well-for-the-web content: html:This is the content for Writing well for the web.
- heading: text: Writing well for specialists content: html:This is the content for Writing well for specialists.
- heading: text: Know your audience content: html:This is the content for Know your audience.
- heading: text: How people read content: html:This is the content for How people read.
condensed_layout: description: | This is for when a smaller accordion is required. Since smaller screens trigger a single column layout, this modifier only makes the accordion smaller when viewed on large screens. data: condensed: true items: - heading: text: Understanding agile project management content: html: '