Disclosures and Accordions
Introduction
Expanding and collapsing widgets are often used to reduce the amount of scrolling required by allowing a user to bypass or collapse content. There are two types of these content area widgets: disclosures and accordions.
A disclosure, also known as a "Show/Hide" widget or "twisty", is the basic content area. It consists of a trigger button that toggles the visibility of the content, and the content area itself.
A disclosure widget can be made using buttons, JavaScript, and ARIA, or simply by using HTML <details> and <summary> elements.
This is the summary of the disclosure
And here are the details of the disclosure!
<summary>This is the summary of the disclosure</summary>
<p>And here are the details of the disclosure!</p>
</details>
The <details> element can be given an open attribute to cause the summary to be visible by default.
Accordions are multiple sections of content areas that are visually "stacked" together. Each section has a trigger button that expands and collapses the section's content area with only one of the sections visible at a time.
A basic accordion can be created with multiple <details> elements each with the same name attribute value.
Legislative Branch
Makes the laws and is composed of Congress, which includes the Senate and the House of Representatives.
Executive Branch
Enforces the laws and is led by the President, along with federal agencies and the Cabinet.
Judicial Branch
Interprets the laws and is headed by the Supreme Court and other federal courts.
<summary>Legislative Branch</summary>
<p>Makes the laws and is composed of Congress, which includes the Senate and the House of Representatives.</p>
</details>
<details name="branch">
<summary>Executive Branch</summary>
<p>Enforces the laws and is led by the President, along with federal agencies and the Cabinet.</p>
</details>
<details name="branch">
<summary>Judicial Branch</summary>
<p>Interprets the laws and is headed by the Supreme Court and other federal courts.</p>
</details>
Accordions can also be created using JavaScript and ARIA as shown in the WAI‑ARIA Accordion Example.
Potential Problems
Disclosures and accordions created using <details> and <summary> have built-in accessibility. The <summary> element properly functions like a button, and the expanded state (open or closed) is presented to assistive technologies. The problems below only occur when other elements or scripting are used.
Disclosures and accordions created using buttons, JavaScript, and ARIA can be implemented incorrectly and create accessibility issues. Below are some common issues and how to address them.
Triggers cannot receive keyboard focus
Sometimes, elements that are not meant to be interactive (e.g., <div>, <p>, or <a> without the href attribute) are made interactive through JavaScript event handlers like onclick. If one of these is made into the trigger element for a content area, keyboard and screen reader users are unable to directly navigate to it. The best way to solve this problem is to use a standard <button> element as the trigger element.
Triggers are not buttons
The trigger element that expands and collapses the content area should be coded as a standard <button>. Sometimes the trigger element is incorrectly coded as a link. Using links as trigger elements can make navigation confusing for keyboard and screen reader users. Links are about navigation, for example navigating to a new page or to a particular place in a page. Buttons are about function, for example expanding and collapsing a content area.
Links also have different keyboard interactions than buttons. Buttons can be activated with Enter or Spacebar, but links are only activated by Enter.
Triggers don't indicate the state of the content area
Screen reader users need to be informed of the trigger's function and whether the content area is expanded or collapsed. Disclosures made with the HTML <details>/<summary> elements have this functionality built in. Disclosures and accordions made with ARIA must have the aria‑expanded="true|false" attribute applied to the trigger button.
Scripting must be used to dynamically update the aria‑expanded="true|false" attribute value each time the trigger button is activated, or it can become inaccurate. The attribute value must always align with the state of the content visibility.
Here's an example of a dynamically updating disclosure. You can use a screen reader to test if the trigger button correctly indicates the state of a content area. You can also monitor the attribute value in browser Developer Tools.
When the trigger button of an expanded content area receives keyboard focus, a screen reader should announce "expanded" or "collapsed", in addition to the text of the trigger button. This not only indicates the current state, but indicates to the user that activating the button will change the state to the opposite value.
When the user activates the trigger button and changes the state of the content area, a screen reader should announce the new state. So if the user activates the trigger button of a collapsed content area, expanding the content area, a screen reader should announce "expanded".
Elements in collapsed content areas receive keyboard focus
Content areas may contain elements that can receive keyboard focus, most commonly links or buttons. Incorrectly implemented disclosures and accordions can have elements in their content areas that receive keyboard focus while the content area containing them is collapsed and the contents visually hidden. This results in the visual focus indicators being lost. This can confuse users and cause them to lose their place.
When the content area is collapsed, the contents should not be accessible, including elements that otherwise could receive keyboard focus. Using CSS display:none or the hidden attribute will visually and programmatically hide the contents.