Accordion

<div class="ds_accordion" data-module="ds-accordion">
    <button type="button" class="ds_link  ds_accordion__open-all  js-open-all">Open all <span class="visually-hidden">sections</span></button>

    <div class="ds_accordion-item">
        <input type="checkbox" class="visually-hidden  ds_accordion-item__control" id="panel-1" aria-labelledby="panel-1-heading">
        <div class="ds_accordion-item__header">
            <h2 id="panel-1-heading" class="ds_accordion-item__title">
                Healthcare for veterans
            </h2>
            <span aria-hidden="true" class="ds_accordion-item__indicator"></span>
            <label class="ds_accordion-item__label" for="panel-1"><span class="visually-hidden">Show this section</span></label>
        </div>
        <div class="ds_accordion-item__body">
            <p>Veterans are entitled to the same healthcare as any citizen. And there are <a href="#">health care options and support</a> available specifically for veterans.  </p>
            <p>If you have a health condition that's related to your service, you're entitled to priority treatment based on clinical need. </p>
        </div>
    </div>

    <div class="ds_accordion-item">
        <input type="checkbox" class="visually-hidden  ds_accordion-item__control" id="panel-2" aria-labelledby="panel-2-heading">
        <div class="ds_accordion-item__header">
            <h2 id="panel-2-heading" class="ds_accordion-item__title">
                Employability for veterans
            </h2>
            <span class="ds_accordion-item__indicator"></span>
            <label class="ds_accordion-item__label" for="panel-2"><span class="visually-hidden">Show this section</span></label>
        </div>
        <div class="ds_accordion-item__body">
            <p>If you're looking for a job, there are several organisations that can help you <a href="#">find a job or develop new skills</a>.</p>
        </div>
    </div>

    <div class="ds_accordion-item">
        <input type="checkbox" class="visually-hidden  ds_accordion-item__control" id="panel-3" aria-labelledby="panel-3-heading">
        <div class="ds_accordion-item__header">
            <h2 id="panel-3-heading" class="ds_accordion-item__title">
                Housing for veterans
            </h2>
            <span class="ds_accordion-item__indicator"></span>
            <label class="ds_accordion-item__label" for="panel-3"><span class="visually-hidden">Show this section</span></label>
        </div>
        <div class="ds_accordion-item__body">
            <p>If you need <a href="#">help finding a place to live</a> there's support specifically for veterans.</p>
        </div>
    </div>
</div>

About this component

An accordion is made up of multiple expandable and collapsible sections. Users can open or close an accordion section to reveal or hide the content within it. 

When to use accordions

Use accordions to organise content, reduce clutter and shorten page length.

They can help users:

• get an overview of the content on a page
• focus only on the content that’s relevant to them, which reduces cognitive load
• scan information that might otherwise be on different pages

For example, accordions can be helpful if you can split the content for different user groups. A user can identify and read only the content that’s useful to them.

When not to use accordions

Do not use accordions if:

• it’s content all or most users need
• the content is complex and difficult to split up
• there's little visible content left on the page – accordions can make a page look empty so users may abandon it
• it will disrupt the user’s reading flow and understanding – for example, in news articles
• the amount of content inside an accordion makes the page slow to load

Alternatives to accordions

Use accordions carefully. This is because they: 

• hide content so users could miss information 
• increase the interaction cost for users, as they may have to spend time opening and closing accordion sections 
• are not always noticed and understood by all users 

Try other ways of displaying your content before choosing accordions. For example, by: 

• splitting the content across multiple pages 
• simplifying and reducing the amount of content 
• keeping the content on one page, separated by headings 

Decide between accordions, tabs or details

The details component and tabs component also hide information that users can choose to reveal. 

Do not use any of these components within one another.  

Consider using accordions instead of tabs if: 

• the user needs to see more than one section of content at a time – accordions can show multiple sections at a time, unlike tabs  
• there are many content sections – accordions can fit more sections as they’re stacked vertically, unlike tabs which sit horizontally on desktop devices
• users do not need to see the content on page load – accordions are closed on page load, unlike tabs which can show content on page load  
• users do not need to switch quickly between sections – accordions push content down the page whereas tabs stay in the same position 

Do not use accordions if you only have a single piece of content. Use the details component instead.

How to use this component

An accordion starts with all sections closed. 

To open a section, users interact with the section heading, which is a button. 

Accordion headings use the link focus state to show users which section they’re interacting with. 

Multiple accordion sections can be open at the same time. 

Do not leave accordion sections empty. Remove the accordion section if you do not have content for it.   

Do not put accordions within accordions as it will make the content difficult to find. 

Write clear headings

The heading button includes: 

• heading text 
• an arrow icon 
• ‘Open’ or ‘Close’ call to action text 

Accordion heading text must: 

• be short and descriptive so users can quickly work out if they need to open the accordion section 
• use sentence case

Using the ‘Open all’/’Close all’ button

Place an ‘Open all’/'Close all' button at the top of the accordion. This function lets users expand or collapse all sections at once. This helps users to scan the content. 

The accordion component uses JavaScript. When JavaScript is not available, the ‘Open all’/‘Close all’ button will not appear. 

Review performance data

You should look at performance data to check your accordions are helping your users.  

For example, check how many users are: 

• opening 1 or 2 sections – this suggests they’re finding the information relevant to them 
• using the ‘Open all’ button – this suggests they’re not able to find the information they need 

If you find evidence users are finding your accordions difficult to use, you could: 

• try different heading text 
• present the information in a different way 

Website analytics

Interacting with an accordion heading opens or closes the section. Interacting with the ‘Open all’ or ‘Close all’ button opens or closes all sections.

These actions are tracked using: 

• the page path 
• the selected text (also known as click text) 
• a data attribute that shows the action and item number 

The Design System’s ‘tracking’ script automatically adds these data attributes.

Accessibility

Accordion heading levels

Accordion headings always look the same regardless of which heading level you use. However, you must mark them up with the correct heading level so screen readers understand the page hierarchy.

Choose the accordion heading level as if it were a normal heading. For example, if the section starts with an H2, use H3 for the accordion headings within it.

Accessible Rich Internet Applications (ARIA) attributes

Accordion headings use:

• aria-controls to tell screen readers which piece of content the heading button controls
• the aria-expanded attribute to tell screen readers whether an accordion section is open or closed – when the section is open, it is set to “true”

The ‘Open'/'Close’ button on the accordion header uses aria-hidden as this button is not needed for screen readers.

We have followed suggestions from the W3C’s WAI-ARIA authoring practices for accordions.

Related components

The search filters pattern uses accordions to group types of filter.