Disclosures and accordions (show/hide)
Understand how to create and test for accessible disclosures and accordions that show and hide content.
On this page
- What are disclosures and accordions?
- Create accessible disclosures
- Create accessible accordions
- Other accessibility considerations
- Testing disclosures and accordions
What are disclosures and accordions?
Disclosures and accordions are user interface (UI) components for showing and hiding, or expanding and collapsing, some content.
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.
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 the native HTML
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
HTML provides the functionality for disclosures through the
<summary> elements. Disclosure widgets using the
For a definition of these elements, see:
- <details>: The Details disclosure element — MDN Web Docs
- The details element — HTML Living Standard.
To make accessible disclosure widgets using these elements, see:
- The details and summary elements, again — Scott O’Hara
- Details / Summary Are Not [insert control here] — Adrian Roselli.
<summary> not currently recommended
As of September 2023,
<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,
<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
<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
“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.
<button> or an element with a role of
button is invalid (unless that button is a
<summary> element inside a
In a disclosure built with
<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
<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.
For more details on headings in
<summary> elements, see:
<summary>can have nested interactive elements and headings — The details and summary elements, again — Scott O’Hara
- Disallow interactive content in
<summary>(issue #2272) — whatwg/html — GitHub.
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.
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.
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
<summary> elements, Chrome and Edge’s find-in-page function will find matches within the collapsed
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
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.
- its button component is a
<button>element or otherwise has a role of
aria-expandedattribute 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
role="region"if the accordion is important enough to be an ARIA
- if the accordion has a heading, the heading element’s
idis referenced in an
aria-labelledbyattribute on the accordion’s container element.