Disclosures and accordions (show/hide)

Understand how to create and test for accessible disclosures and accordions that show and hide content.

What are disclosures and accordions?

Disclosures and accordions are user interface (UI) components for showing and hiding, or expanding and collapsing, some content.

Disclosures

A disclosure is a single component or widget for showing and hiding one section of content. It’s basically a button that expands and collapses the content that comes right after it. The component includes a simple icon or graphical element that helps visually identify it as interactive, and it changes to indicate the widget’s current state, expanded or collapsed.

A disclosure can be open or closed to start with. When a disclosure is closed, its content is collapsed or hidden and is not available to any user, including assistive technology users.

Example of a disclosure

What is web accessibility?

Web accessibility is all about ensuring all people, including disabled people, can perceive, operate, and understand web content.

Accordions

An accordion can be thought of as a collection of 2 or more disclosures one after the other.

An accordion can be made so that only one section or panel of content is visible or expanded at once. When expanding a collapsed section in the accordion, the previously expanded section collapses. But most accordions allow the user to expand or collapse any of the panels they wish. There are often extra buttons available for quickly expanding or collapsing all the accordion panels at once.

For an example of an accordion, see the list of Common text-level semantic elements — Web Content Type: Text content.

Create accessible disclosures

There are 2 main ways to make a disclosure widget:

using ARIA and JavaScript to build a custom disclosure
using the native HTML <details> and <summary> elements.

Custom disclosures using ARIA and JavaScript

The WAI-ARIA Authoring Practices has guidance on implementing accessible custom disclosures. See Disclosure (Show/Hide) Pattern — ARIA Authoring Practices Guide — W3C.

For a script that can be used to create different variations of a custom disclosure element, see ARIA Disclosure Widgets — Scott O’Hara.

Note: Accessible Rich Internet Applications (WAI-ARIA), or just ARIA, is a W3C technology for programmatically adding semantic information about content — such as its name, role, state or other properties. ARIA is intended to be used when the host markup language — for example, HTML — does not include elements or attributes with the semantics needed to represent the content.

When ARIA is used correctly, it enables assistive technologies (AT), especially screen readers, to relay the necessary semantic information about the content to the user.

As a rule, do not use ARIA if a native HTML element or attribute with the needed semantics or features already exists.

For more information, see:

Native HTML disclosure using `<details>` and `<summary>`

HTML provides the functionality for disclosures through the <details> and <summary> elements. Disclosure widgets using the <details> and <summary> elements are easy to implement and require no JavaScript. The expanding/collapsing functionality is already built in.

For a definition of these elements, see:

To make accessible disclosure widgets using these elements, see:

`<details>` and `<summary>` not currently recommended

As of September 2023, <details> and <summary> are still not accessibility supported for a general audience. This is because of a long-standing bug with Safari and the VoiceOver screen reader on iOS. On an iPhone or iPad, when a VoiceOver user with Safari comes across a disclosure made from these elements, they are not told it is an interactive widget or if it’s expanded or collapsed. For details, see Bug 108979 - details element not exposed as disclosure widget to accessibility APIs — WebKit Bugzilla).

As such, where some of a site’s visitors are expected to be using VoiceOver on an iPhone or iPad, <details> and <summary> cannot be relied on to make an accessible disclosure widget that meets WCAG 2.

Create accessible accordions

To make an accordion, combine 2 or more disclosures in a group.

For information on how to build an accessible accordion component from scratch, see Collapsible Sections — Inclusive Components.

See also the W3C’s ARIA Authoring Practices Guide, Accordion Pattern (Sections With Show/Hide Functionality) — ARIA Authoring Practices Guide — W3C. Note that for the W3C, an accordion is always a set of interactive headings that serve as controls for showing and hiding associated content.)

To make an accordion from a set of disclosures using <details> and <summary>, see Progressively Enhanced HTML Accordion — Adrian Roselli.

Group the disclosures

To programmatically group the disclosures in the accordion, consider grouping them in a section of their own with a heading. This tells assistive technologies that all the individual disclosures are part of a set, and the heading introduces them.

A simple way to do this is by applying role="group" to a <div> containing all of the disclosures. It there’s a heading for the accordion, use the aria-labelledby attribute on the <div> to reference the heading’s id. This allows the heading to serve as the group’s accessible name.

If the accordion is important enough that users might want to navigate to it directly or it could be listed in the page’s table of contents, group the disclosures in a <section> element and give it an accessible name. This will make the accordion an ARIA region landmark enabling more direct access to the accordion for screen reader users and others.

For guidance on how to do this for a set of <details> and <summary> disclosures, see Grouping context — Progressively Enhanced HTML Accordion — Adrian Roselli. The procedure is effectively the same for a group of custom ARIA and JavaScript disclosures.

“Expand all” and “Collapse all” buttons

Consider adding “Expand all” and “Collapse all” buttons to an accordion so that users can quickly and easily show or hide all the accordion panels at once. For more, see Expand/Collapse all — Collapsible Sections — Inclusive Components.

Other accessibility considerations

For an informative discussion of how GOV.UK tested and improved the accessibility of their accordions, see How we made the GOV.UK accordion component more accessible.

Headings in disclosures

Depending on context, the part of a disclosure that expands and collapses the widget can include a heading element. This is more common in an accordion where several sections of content, each with its own heading, are collapsed into a set of disclosures. But a single disclosure could also use a heading.

If a disclosure widget does start with a heading, make sure that:

any headings inside the disclosure’s content panel are of a lower level than the heading used to expand and collapse the widget
unrelated content that comes after the disclosure widget starts with its own heading — otherwise it will be subsumed by the preceding disclosure widget’s heading, setting up an incorrect relationship between the unrelated content and the disclosure that comes before it.

Headings in custom ARIA and JavaScript disclosures

If a disclosure is built with ARIA and JavaScript, make sure to nest the element that serves as the disclosure’s button inside the heading. Putting a heading inside a <button> or an element with a role of button is invalid (unless that button is a <summary> element inside a <details> element).

Headings in `<details>` and `<summary>` disclosures

In a disclosure built with <details> and <summary>, the <summary> serves as the button for expanding/collapsing the widget. According to the definition of the <summary> element in the HTML Living Standard, it can include headings and other interactive elements like <input> and <a href> elements.

However, this is a little unusual as most browsers expose the <summary> element with a role of button, and just like a <button>, elements with a role of button are not expected to include headings or interactive content. In fact, headings or interactive elements inside an element with a role of button are supposed to have their semantics removed.

The result is that headings (or interactive elements) inside a <summary> element are inconsistently exposed by browsers to screen readers. As such, it’s difficult to know if a screen reader user will be able to navigate to headings inside <summary> elements or even be told that they exist.

If a heading structure is important for the disclosures you’re building, consider creating custom disclosures using ARIA and JavaScript where the disclosure’s button is nested within the heading element.

For more details on headings in <summary> elements, see:

Position disclosure icon next to button text

Different icons get used to identify a disclosure widget and its current state, open or closed. It could be an arrow, a triangle, the ‘+’ and ‘-’ signs, or something else.

No matter what graphical symbol is used, visually position it immediately next to the disclosure’s button text. In left-to-right languages like English or Māori, it’s best to put the icon to the left of the button’s text. This helps ensure that screen magnification users, who can only see a small part of the screen at a time, will see the disclosure’s icon at the same time as they read its button text. This enables the user to identify the widget as a disclosure and know its current state.

In some designs, the icon is aligned to the right side of the page, leaving it visually located some distance away from the disclosure’s left-aligned button text. Screen magnification users are likely not to see the icon when they’re reading the disclosure’s button text. In this case, they will not know that the text is part of a widget they can interact with.

Disclosures hide content from users

A disclosure typically hides content from users. This can make it difficult for users to find that content. To access the content, the user must first reveal it by interacting with the widget. Only then will they know if it’s the content they were looking or hoping to find. It can be helpful to remember this when considering the use of disclosures for presenting content to users.

Find-in-page

Content that is hidden from users, including assistive technology users, is not searched when using the find-in-page search function that all browsers have.

Right now, disclosures built with ARIA and JavaScript use the CSS, display:none, to hide the collapsed content. This prevents browsers’ in-page search from finding matches within a collapsed disclosure.

However, if a disclosure uses the <details> and <summary> elements, Chrome and Edge’s find-in-page function will find matches within the collapsed <details> element.

This behaviour is related to a new hidden until found state of the HTML hidden attribute. It’s currently supported only in Chrome and Edge, but once there’s broad support for the attribute’s until-found value, custom disclosures can use it to hide content in a way that still works with a browser’s in-page search. By then, it’s likely that Safari and Firefox will also support find-in-page for content within collapsed <details> elements.

Testing disclosures and accordions

For each disclosure, check that:

its structure, content and functionality are programmatically expressed in semantic markup, and that elements have accessible names, roles, states and properties where needed. See:
it is keyboard accessible. See Testing keyboard accessibility — Knowledge Area: Keyboard accessibility.
all text, meaningful graphical elements and interactive components have sufficient colour contrast and do not rely on colour alone to convey any information. See Testing colour and contrast — Knowledge Area: Colour and contrast.

For a custom disclosure that uses ARIA and JavaScript, check that:

its button component is a <button> element or otherwise has a role of button and an aria-expanded attribute whose value represents the current state of the disclosure
if the part of a disclosure that expands and collapses the widget includes a heading:
- the button component is nested within the heading element, and not the other way around
- the content that comes after the disclosure widget starts with a new heading.

For an accordion or set of disclosures, check that:

the accordion is marked up as a group, with all its disclosures contained in a <div> or <section> element with role="group", or role="region" if the accordion is important enough to be an ARIA region landmark.
if the accordion has a heading, the heading element’s id is referenced in an aria-labelledby attribute on the accordion’s container element.