<divclass="govuk-accordion__section "><divclass="govuk-accordion__section-header"><h2class="govuk-accordion__section-heading"><spanclass="govuk-accordion__section-button"id="accordion-default-heading-1">
Writing well for the web
</span></h2></div><divid="accordion-default-content-1"class="govuk-accordion__section-content"aria-labelledby="accordion-default-heading-1"><pclass='govuk-body'>This is the content for Writing well for the web.</p></div></div><divclass="govuk-accordion__section "><divclass="govuk-accordion__section-header"><h2class="govuk-accordion__section-heading"><spanclass="govuk-accordion__section-button"id="accordion-default-heading-2">
Writing well for specialists
</span></h2></div><divid="accordion-default-content-2"class="govuk-accordion__section-content"aria-labelledby="accordion-default-heading-2"><pclass='govuk-body'>This is the content for Writing well for specialists.</p></div></div><divclass="govuk-accordion__section "><divclass="govuk-accordion__section-header"><h2class="govuk-accordion__section-heading"><spanclass="govuk-accordion__section-button"id="accordion-default-heading-3">
Know your audience
</span></h2></div><divid="accordion-default-content-3"class="govuk-accordion__section-content"aria-labelledby="accordion-default-heading-3"><pclass='govuk-body'>This is the content for Know your audience.</p></div></div><divclass="govuk-accordion__section "><divclass="govuk-accordion__section-header"><h2class="govuk-accordion__section-heading"><spanclass="govuk-accordion__section-button"id="accordion-default-heading-4">
How people read
</span></h2></div><divid="accordion-default-content-4"class="govuk-accordion__section-content"aria-labelledby="accordion-default-heading-4"><pclass='govuk-body'>This is the content for How people read.</p></div></div></div>
<p>
Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
</p>
<p>
Some options are required for the macro to work; these are marked as "Required" in the option description.
</p>
<p>
If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against <a href="https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting">cross-site scripting exploits</a>.
</p>
<table class="govuk-table app-options__table" id="options-accordion-example--primary">
<caption class="govuk-table__caption govuk-heading-m govuk-visually-hidden">Primary options</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
<th class="govuk-table__header" scope="col">Description</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">id</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
Must be unique across the domain of your service (as the expanded state of individual instances of the component persists across page loads using <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage"><code>sessionStorage</code></a>). Used as an <code>id</code> in the HTML for the accordion as a whole, and also as a prefix for the <code>id</code>s of the section contents and the buttons that open them, so that those <code>id</code>s can be the target of <code>aria-labelledby</code> and <code>aria-control</code> attributes.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">headingLevel</th>
<td class="govuk-table__cell ">integer</td>
<td class="govuk-table__cell ">
Heading level, from <code>1</code> to <code>6</code>. Default is <code>2</code>.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">classes</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
Classes to add to the accordion.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">attributes</th>
<td class="govuk-table__cell ">object</td>
<td class="govuk-table__cell ">
HTML attributes (for example data attributes) to add to the accordion.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">hideAllSectionsText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
The text content of the 'Hide all sections' button at the top of the accordion when all sections are expanded.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">hideSectionText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
The text content of the 'Hide' button within each section of the accordion, which is visible when the section is expanded.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">hideSectionAriaLabelText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
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'.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">showAllSectionsText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
The text content of the 'Show all sections' button at the top of the accordion when at least one section is collapsed.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">showSectionText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
The text content of the 'Show' button within each section of the accordion, which is visible when the section is collapsed.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">showSectionAriaLabelText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
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'.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">items</th>
<td class="govuk-table__cell ">array</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
An array of sections within the accordion.
See <a href="#options-accordion-example--items">items</a>.
</td>
</tr>
</tbody>
</table>
<table class="govuk-table app-options__table" id="options-accordion-example--items">
<caption class="govuk-table__caption govuk-heading-m ">Options for items</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
<th class="govuk-table__header" scope="col">Description</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">heading.text</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
The title of each section. If <code>heading.html</code> is supplied, this is ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">heading.html</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
The HTML content of the header for each section. Used as the title for each section. The header is inside the HTML <code><button></code> element, so you can only add <a href="https://html.spec.whatwg.org/#phrasing-content">phrasing content</a> to it.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">summary.text</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
Text content for summary line. If <code>summary.html</code> is supplied, this is ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">summary.html</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
The HTML content for the summary line. The summary line is inside the HTML <code><button></code> element, so you can only add <a href="https://html.spec.whatwg.org/#phrasing-content">phrasing content</a> to it.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">content.text</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
The text content of each section, which is hidden when the section is closed. If <code>content.html</code> is supplied, this is ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">content.html</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
The HTML content of each section, which is hidden when the section is closed.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">expanded</th>
<td class="govuk-table__cell ">boolean</td>
<td class="govuk-table__cell ">
Sets whether the section should be expanded when the page loads for the first time. Defaults to <code>false</code>.
</td>
</tr>
</tbody>
</table>
{{ govukAccordion({
id: "accordion-default",
items: [
{
heading: {
text: "Writing well for the web"
},
content: {
html: "<p class='govuk-body'>This is the content for Writing well for the web.</p>"
}
},
{
heading: {
text: "Writing well for specialists"
},
content: {
html: "<p class='govuk-body'>This is the content for Writing well for specialists.</p>"
}
},
{
heading: {
text: "Know your audience"
},
content: {
html: "<p class='govuk-body'>This is the content for Know your audience.</p>"
}
},
{
heading: {
text: "How people read"
},
content: {
html: "<p class='govuk-body'>This is the content for How people read.</p>"
}
}
]
}) }}
When to use this component
Only use an accordion if there's evidence it’s helpful for the user to:
see an overview of multiple, related sections of content
choose to show and hide sections that are relevant to them
look across information that might otherwise be on different pages
For example, an accordion can work well if the user needs to reveal and compare information that’s relevant to them.
Accordions can also work well for people who use a service regularly. For example, users of caseworking systems who need to do familiar tasks quickly.
Test with users to decide if using an accordion outweighs the potential problems with hiding content.
When not to use this component
Accordions hide content from the user. Not all users will notice them or understand how they work. For this reason, you should only use them in specific situations and if user research supports it.
Do not use an accordion for content that all users need to see.
Test your content without an accordion first. Well-written and structured content, as shown in the Content design: writing for GOV.UK guidance, can remove the need to use an accordion.
It’s usually better to:
simplify and reduce the amount of content
split the content across multiple pages
keep the content on a single page, separated by headings
use a list of links at the start of the page (known as 'anchor links') to take the user to particular sections of a page
Accordions work best for simple content and links. Do not use accordions to split up a series of questions. Use separate pages instead.
Do not put accordions within accordions, as it will make content difficult to find.
Do not use the accordion component if the amount of content inside will make the page slow to load.
Decide between using accordions, tabs and details
Accordions, tabs and details all work by hiding sections of content which a user can choose to reveal. Avoid using any of these components within one another.
If you decide to use one of these components, consider if:
the user needs to look at more than one section at a time — an accordion can show multiple sections at a time, unlike tabs
the user needs to switch quickly between sections — tabs can show content without pushing other sections down the page, unlike accordions
there are many sections of content — accordions can fit more sections as they’re arranged vertically, unlike tabs which are arranged horizontally
there’s only one or two pieces of short, less important content — the details component is more suitable as it’s visually smaller and less prominent than an accordion or tabs
How it works
There are 2 ways to use the accordion component. You can use HTML or, if you’re using Nunjucks or the GOV.UK Prototype Kit, you can use the Nunjucks macro.
The accordion component uses JavaScript. When JavaScript is not available, users will see all the content displayed with the section labels as headings.
Section heading buttons
An accordion will usually start with all sections hidden. To show a section, the user can interact anywhere in the heading button.
The heading button includes all of these areas:
heading text
summary line (if you decide to add one)
call-to-action text to 'show' or 'hide'
For users of screen readers, all the text in the button will be read as a single statement (separated by commas to allow for slight pauses). There’s also some visually hidden content in the heading text to help announce the call-to-action as 'show this section' or 'hide this section'.
<divclass="govuk-accordion__section "><divclass="govuk-accordion__section-header"><h2class="govuk-accordion__section-heading"><spanclass="govuk-accordion__section-button"id="accordion-default-heading-1">
Writing well for the web
</span></h2></div><divid="accordion-default-content-1"class="govuk-accordion__section-content"aria-labelledby="accordion-default-heading-1"><pclass='govuk-body'>This is the content for Writing well for the web.</p></div></div><divclass="govuk-accordion__section "><divclass="govuk-accordion__section-header"><h2class="govuk-accordion__section-heading"><spanclass="govuk-accordion__section-button"id="accordion-default-heading-2">
Writing well for specialists
</span></h2></div><divid="accordion-default-content-2"class="govuk-accordion__section-content"aria-labelledby="accordion-default-heading-2"><pclass='govuk-body'>This is the content for Writing well for specialists.</p></div></div><divclass="govuk-accordion__section "><divclass="govuk-accordion__section-header"><h2class="govuk-accordion__section-heading"><spanclass="govuk-accordion__section-button"id="accordion-default-heading-3">
Know your audience
</span></h2></div><divid="accordion-default-content-3"class="govuk-accordion__section-content"aria-labelledby="accordion-default-heading-3"><pclass='govuk-body'>This is the content for Know your audience.</p></div></div><divclass="govuk-accordion__section "><divclass="govuk-accordion__section-header"><h2class="govuk-accordion__section-heading"><spanclass="govuk-accordion__section-button"id="accordion-default-heading-4">
How people read
</span></h2></div><divid="accordion-default-content-4"class="govuk-accordion__section-content"aria-labelledby="accordion-default-heading-4"><pclass='govuk-body'>This is the content for How people read.</p></div></div></div>
<p>
Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
</p>
<p>
Some options are required for the macro to work; these are marked as "Required" in the option description.
</p>
<p>
If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against <a href="https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting">cross-site scripting exploits</a>.
</p>
<table class="govuk-table app-options__table" id="options-accordion-second-example--primary">
<caption class="govuk-table__caption govuk-heading-m govuk-visually-hidden">Primary options</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
<th class="govuk-table__header" scope="col">Description</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">id</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
Must be unique across the domain of your service (as the expanded state of individual instances of the component persists across page loads using <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage"><code>sessionStorage</code></a>). Used as an <code>id</code> in the HTML for the accordion as a whole, and also as a prefix for the <code>id</code>s of the section contents and the buttons that open them, so that those <code>id</code>s can be the target of <code>aria-labelledby</code> and <code>aria-control</code> attributes.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">headingLevel</th>
<td class="govuk-table__cell ">integer</td>
<td class="govuk-table__cell ">
Heading level, from <code>1</code> to <code>6</code>. Default is <code>2</code>.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">classes</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
Classes to add to the accordion.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">attributes</th>
<td class="govuk-table__cell ">object</td>
<td class="govuk-table__cell ">
HTML attributes (for example data attributes) to add to the accordion.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">hideAllSectionsText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
The text content of the 'Hide all sections' button at the top of the accordion when all sections are expanded.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">hideSectionText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
The text content of the 'Hide' button within each section of the accordion, which is visible when the section is expanded.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">hideSectionAriaLabelText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
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'.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">showAllSectionsText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
The text content of the 'Show all sections' button at the top of the accordion when at least one section is collapsed.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">showSectionText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
The text content of the 'Show' button within each section of the accordion, which is visible when the section is collapsed.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">showSectionAriaLabelText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
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'.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">items</th>
<td class="govuk-table__cell ">array</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
An array of sections within the accordion.
See <a href="#options-accordion-second-example--items">items</a>.
</td>
</tr>
</tbody>
</table>
<table class="govuk-table app-options__table" id="options-accordion-second-example--items">
<caption class="govuk-table__caption govuk-heading-m ">Options for items</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
<th class="govuk-table__header" scope="col">Description</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">heading.text</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
The title of each section. If <code>heading.html</code> is supplied, this is ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">heading.html</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
The HTML content of the header for each section. Used as the title for each section. The header is inside the HTML <code><button></code> element, so you can only add <a href="https://html.spec.whatwg.org/#phrasing-content">phrasing content</a> to it.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">summary.text</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
Text content for summary line. If <code>summary.html</code> is supplied, this is ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">summary.html</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
The HTML content for the summary line. The summary line is inside the HTML <code><button></code> element, so you can only add <a href="https://html.spec.whatwg.org/#phrasing-content">phrasing content</a> to it.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">content.text</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
The text content of each section, which is hidden when the section is closed. If <code>content.html</code> is supplied, this is ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">content.html</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
The HTML content of each section, which is hidden when the section is closed.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">expanded</th>
<td class="govuk-table__cell ">boolean</td>
<td class="govuk-table__cell ">
Sets whether the section should be expanded when the page loads for the first time. Defaults to <code>false</code>.
</td>
</tr>
</tbody>
</table>
{{ govukAccordion({
id: "accordion-default",
items: [
{
heading: {
text: "Writing well for the web"
},
content: {
html: "<p class='govuk-body'>This is the content for Writing well for the web.</p>"
}
},
{
heading: {
text: "Writing well for specialists"
},
content: {
html: "<p class='govuk-body'>This is the content for Writing well for specialists.</p>"
}
},
{
heading: {
text: "Know your audience"
},
content: {
html: "<p class='govuk-body'>This is the content for Know your audience.</p>"
}
},
{
heading: {
text: "How people read"
},
content: {
html: "<p class='govuk-body'>This is the content for How people read.</p>"
}
}
]
}) }}
Write clear button text
Write the heading and summary line like any other button text. Use sentence case, describe the content that will show, and keep it short.
Users of screen readers might find it difficult to navigate the accordion if the button text is too long.
If you struggle to come up with clear button text, it might be because the way you’ve separated the content is not clear. Organise sections in a way that makes sense to users, based on their needs.
Adding a summary line
Only add a summary line if it’s actually needed, as it's likely to make the button text too long.
If you’ve decided that you need the summary line, you must make it as short as possible.
<divclass="govuk-accordion__section "><divclass="govuk-accordion__section-header"><h2class="govuk-accordion__section-heading"><spanclass="govuk-accordion__section-button"id="accordion-with-summary-sections-heading-1">
Understanding agile project management
</span></h2><divclass="govuk-accordion__section-summary govuk-body"id="accordion-with-summary-sections-summary-1">
Introductions, methods, core features.
</div></div><divid="accordion-with-summary-sections-content-1"class="govuk-accordion__section-content"aria-labelledby="accordion-with-summary-sections-heading-1"><ulclass="govuk-list"><li><aclass="govuk-link"href="#">Agile and government services: an introduction</a></li><li><aclass="govuk-link"href="#">Agile methods: an introduction</a></li><li><aclass="govuk-link"href="#">Core principles of agile</a></li></ul></div></div><divclass="govuk-accordion__section "><divclass="govuk-accordion__section-header"><h2class="govuk-accordion__section-heading"><spanclass="govuk-accordion__section-button"id="accordion-with-summary-sections-heading-2">
Working with agile methods
</span></h2><divclass="govuk-accordion__section-summary govuk-body"id="accordion-with-summary-sections-summary-2">
Workspaces, tools and techniques, user stories, planning.
</div></div><divid="accordion-with-summary-sections-content-2"class="govuk-accordion__section-content"aria-labelledby="accordion-with-summary-sections-heading-2"><ulclass="govuk-list"><li><aclass="govuk-link"href="#">Creating an agile working environment</a></li><li><aclass="govuk-link"href="#">Agile tools and techniques</a></li><li><aclass="govuk-link"href="#">Set up a team wall</a></li><li><aclass="govuk-link"href="#">Writing user stories</a></li><li><aclass="govuk-link"href="#">Planning in agile</a></li><li><aclass="govuk-link"href="#">Deciding on priorities</a></li><li><aclass="govuk-link"href="#">Developing a roadmap</a></li></ul></div></div><divclass="govuk-accordion__section "><divclass="govuk-accordion__section-header"><h2class="govuk-accordion__section-heading"><spanclass="govuk-accordion__section-button"id="accordion-with-summary-sections-heading-3">
Governing agile services
</span></h2><divclass="govuk-accordion__section-summary govuk-body"id="accordion-with-summary-sections-summary-3">
Principles, measuring progress, spending money.
</div></div><divid="accordion-with-summary-sections-content-3"class="govuk-accordion__section-content"aria-labelledby="accordion-with-summary-sections-heading-3"><ulclass="govuk-list"><li><aclass="govuk-link"href="#">Governance principles for agile service delivery</a></li><li><aclass="govuk-link"href="#">Measuring and reporting progress</a></li><li><aclass="govuk-link"href="#">Spend controls: check if you need approval to spend money on a service</a></li><li><aclass="govuk-link"href="#">Spend controls: apply for approval to spend money on a service</a></li><li><aclass="govuk-link"href="#">Spend controls: the new pipeline process</a></li><li><aclass="govuk-link"href="#">Working across organisational boundaries</a></li></ul></div></div><divclass="govuk-accordion__section "><divclass="govuk-accordion__section-header"><h2class="govuk-accordion__section-heading"><spanclass="govuk-accordion__section-button"id="accordion-with-summary-sections-heading-4">
Phases of an agile project
</span></h2><divclass="govuk-accordion__section-summary govuk-body"id="accordion-with-summary-sections-summary-4">
Discovery, alpha, beta, live and retirement.
</div></div><divid="accordion-with-summary-sections-content-4"class="govuk-accordion__section-content"aria-labelledby="accordion-with-summary-sections-heading-4"><ulclass="govuk-list"><li><aclass="govuk-link"href="#">How the discovery phase works</a></li><li><aclass="govuk-link"href="#">How the alpha phase works</a></li><li><aclass="govuk-link"href="#">How the beta phase works</a></li><li><aclass="govuk-link"href="#">How the live phase works</a></li><li><aclass="govuk-link"href="#">Retiring your service</a></li></ul></div></div></div>
<p>
Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
</p>
<p>
Some options are required for the macro to work; these are marked as "Required" in the option description.
</p>
<p>
If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against <a href="https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting">cross-site scripting exploits</a>.
</p>
<table class="govuk-table app-options__table" id="options-accordion-with-summary-sections-example--primary">
<caption class="govuk-table__caption govuk-heading-m govuk-visually-hidden">Primary options</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
<th class="govuk-table__header" scope="col">Description</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">id</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
Must be unique across the domain of your service (as the expanded state of individual instances of the component persists across page loads using <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage"><code>sessionStorage</code></a>). Used as an <code>id</code> in the HTML for the accordion as a whole, and also as a prefix for the <code>id</code>s of the section contents and the buttons that open them, so that those <code>id</code>s can be the target of <code>aria-labelledby</code> and <code>aria-control</code> attributes.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">headingLevel</th>
<td class="govuk-table__cell ">integer</td>
<td class="govuk-table__cell ">
Heading level, from <code>1</code> to <code>6</code>. Default is <code>2</code>.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">classes</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
Classes to add to the accordion.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">attributes</th>
<td class="govuk-table__cell ">object</td>
<td class="govuk-table__cell ">
HTML attributes (for example data attributes) to add to the accordion.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">hideAllSectionsText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
The text content of the 'Hide all sections' button at the top of the accordion when all sections are expanded.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">hideSectionText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
The text content of the 'Hide' button within each section of the accordion, which is visible when the section is expanded.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">hideSectionAriaLabelText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
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'.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">showAllSectionsText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
The text content of the 'Show all sections' button at the top of the accordion when at least one section is collapsed.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">showSectionText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
The text content of the 'Show' button within each section of the accordion, which is visible when the section is collapsed.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">showSectionAriaLabelText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
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'.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">items</th>
<td class="govuk-table__cell ">array</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
An array of sections within the accordion.
See <a href="#options-accordion-with-summary-sections-example--items">items</a>.
</td>
</tr>
</tbody>
</table>
<table class="govuk-table app-options__table" id="options-accordion-with-summary-sections-example--items">
<caption class="govuk-table__caption govuk-heading-m ">Options for items</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
<th class="govuk-table__header" scope="col">Description</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">heading.text</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
The title of each section. If <code>heading.html</code> is supplied, this is ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">heading.html</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
The HTML content of the header for each section. Used as the title for each section. The header is inside the HTML <code><button></code> element, so you can only add <a href="https://html.spec.whatwg.org/#phrasing-content">phrasing content</a> to it.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">summary.text</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
Text content for summary line. If <code>summary.html</code> is supplied, this is ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">summary.html</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
The HTML content for the summary line. The summary line is inside the HTML <code><button></code> element, so you can only add <a href="https://html.spec.whatwg.org/#phrasing-content">phrasing content</a> to it.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">content.text</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
The text content of each section, which is hidden when the section is closed. If <code>content.html</code> is supplied, this is ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">content.html</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
The HTML content of each section, which is hidden when the section is closed.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">expanded</th>
<td class="govuk-table__cell ">boolean</td>
<td class="govuk-table__cell ">
Sets whether the section should be expanded when the page loads for the first time. Defaults to <code>false</code>.
</td>
</tr>
</tbody>
</table>
{{ govukAccordion({
id: "accordion-with-summary-sections",
items: [
{
heading: {
text: "Understanding agile project management"
},
summary: {
text: "Introductions, methods, core features."
},
content: {
html:
'<ul class="govuk-list">
<li>
<a class="govuk-link" href="#">Agile and government services: an introduction</a>
</li>
<li>
<a class="govuk-link" href="#">Agile methods: an introduction</a>
</li>
<li>
<a class="govuk-link" href="#">Core principles of agile</a>
</li>
</ul>'
}
},
{
heading: {
text: "Working with agile methods"
},
summary: {
text: "Workspaces, tools and techniques, user stories, planning."
},
content: {
html:
'<ul class="govuk-list">
<li>
<a class="govuk-link" href="#">Creating an agile working environment</a>
</li>
<li>
<a class="govuk-link" href="#">Agile tools and techniques</a>
</li>
<li>
<a class="govuk-link" href="#">Set up a team wall</a>
</li>
<li>
<a class="govuk-link" href="#">Writing user stories</a>
</li>
<li>
<a class="govuk-link" href="#">Planning in agile</a>
</li>
<li>
<a class="govuk-link" href="#">Deciding on priorities</a>
</li>
<li>
<a class="govuk-link" href="#">Developing a roadmap</a>
</li>
</ul>'
}
},
{
heading: {
text: "Governing agile services"
},
summary: {
text: "Principles, measuring progress, spending money."
},
content: {
html:
'<ul class="govuk-list">
<li>
<a class="govuk-link" href="#">Governance principles for agile service delivery</a>
</li>
<li>
<a class="govuk-link" href="#">Measuring and reporting progress</a>
</li>
<li>
<a class="govuk-link" href="#">Spend controls: check if you need approval to spend money on a service</a>
</li>
<li>
<a class="govuk-link" href="#">Spend controls: apply for approval to spend money on a service</a>
</li>
<li>
<a class="govuk-link" href="#">Spend controls: the new pipeline process</a>
</li>
<li>
<a class="govuk-link" href="#">Working across organisational boundaries</a>
</li>
</ul>'
}
},
{
heading: {
text: "Phases of an agile project"
},
summary: {
text: "Discovery, alpha, beta, live and retirement."
},
content: {
html:
'<ul class="govuk-list">
<li>
<a class="govuk-link" href="#">How the discovery phase works</a>
</li>
<li>
<a class="govuk-link" href="#">How the alpha phase works</a>
</li>
<li>
<a class="govuk-link" href="#">How the beta phase works</a>
</li>
<li>
<a class="govuk-link" href="#">How the live phase works</a>
</li>
<li>
<a class="govuk-link" href="#">Retiring your service</a>
</li>
</ul>'
}
}
]
}) }}
Structure section headings with the rest of the page
The accordion component shows section headings as <h2> headings. If needed, change the heading level of the section headings to make them fit within the other headings on the page.
Starting with sections open
Users might need some sections to be open from the start. If they leave and then return to the page, they might also need sections they opened to stay open.
If the user leaves and then returns to the page within the same page session, the accordion component will use 'session storage' to remember which sections were open. You can configure sections to start and stay open, but not stay closed.
To see the changes you've made, you may need to create a new 'session'. For example, by opening a page in a new tab or window.
Do not disable sections
Disabling controls is normally confusing for users. If there is no content for a section, either remove the section or, if this would be confusing for your users, explain why there is no content when the section is opened.
Research on this component
We updated this component in December 2021 to solve an accessibility issue where the buttons and section labels might be mistaken for links.
The team made sure the component is accessible, for example that users can interact with it using just the keyboard.
Users that navigate using ‘elements lists’
We need to find out more about users that navigate using ‘elements lists’ of headings, buttons, links and other elements — such as users of speech recognition software and partially-sighted users of screen readers.
For these users, it might not be clear enough that the section headings are considered buttons. This could mislead them to navigate (less efficiently) using the show or hide labels.