Accordions are a common component on most websites. They make it easy to collapse longer content and allow people to skim through headings or questions quickly with minimal scrolling, then expand the ones that are relevant to them for additional information.
If your accordions are not accessible, however, keyboard-only and screen reader users will be unable to access the information in them. Not only is this incredibly frustrating for users, but it could also be a legal violation if an accessibility law covers your website.
Laws worldwide, such as the Americans with Disabilities Act, Section 508, European Accessibility Act, Accessibility Act for Ontarians with Disabilities, and Accessibility for Manitobans Act, require your website (including accordions) to be accessible.
Key Components of Accessible Accordions
Headings
Accordions need to use heading markup around the label or question that opens and closes the accordion. Screen reader users rely on headings to understand and navigate web pages.
The critical importance of headings for screen reader users, is why the HTML details element should not be used to build groups of accordions. The details element is intended to be a standalone component and cannot be used to build groups of accordions. Accordion groups built with the details element can fail multiple Web Content Accessibility Guidelines (WCAG) success criteria.
The headings on your accordions need to be at the correct heading level to properly organize the content and provide a logical structure for the page. For example, accordions might be H2s if they are top-level questions, or they might use H3 tags if nested under an H2 heading for the section.
Buttons
The trigger that opens and closes your accordions needs to be a button. The <button> element has a clear, built-in semantic meaning in HTML. It is inherently focusable and interactive. Using a button tag indicates to users and assistive technologies that an action can be performed.
Accordions should not use links or <a> tags to trigger open/close action. Links are for going somewhere else (to a different page or a different section of the same page), not for triggering and action like expand or collapse.
Wrap the heading around the button
In order to maintain semantic meaning, the <button> should be contained in the heading tag. Don’t add role="button" to the heading. If you do that, the heading will no longer be considered a heading by screen readers and will not appear in the headings list.
Button ARIA: aria-expanded and aria-controls
ARIA (Accessible Rich Internet Applications) are HTML roles and attributes designed to enhance the accessibility of websites and web apps for people with disabilities. ARIA is especially helpful when you’re coding interactive functionality with JavaScript, such as is needed to make accordions open and close. (Learn more about ARIA on MDN web docs.)
You need to include two ARIA attributes on your accordion buttons.
- aria-expanded to indicate if it is opened or closed
- aria-controls to indicate what element the button opens and closes
When the accordion is opened and closed, aria-expanded should change between true and false accordingly.
The aria-controls should have the ID of the container made visible or hidden by the button.
Visible focus indicators
For sighted people who use their keyboard to navigate, there should be a visible outline around the button when they tab to it.
This helps keyboard users to know where their focus is as they tab through the website and lets them know they are on an interactive element.
Acceptable color contrast
All text in the accordion needs to pass color contrast checks and be easy for low-vision users (or people outside on their mobile phones on a sunny day) to read.
We recommend AAA color contrast for important text as much as possible, which has a contrast ratio of 7:1. At a minimum, your text should pass AA color contrast with a ratio of 4.5:1.
Our friend Joe Dolson has a contrast checker you can use.
Icons should not be announced to screen readers
Decorative icons that change with the collapsed or expanded state of the accordion are great visual accents. But these are purely decorative, and screen readers should not announce them.
You can get screen readers to ignore these icons by adding them as CSS background images or, if they are added in the DOM, by adding aria-hidden="true" to them.
Hidden content should not be read by screen readers or keyboard-focusable
Any content that is not visible on the page should not be read out by screen readers or focusable when you use the Tab key to navigate through the website.
The easiest way to achieve this it to include the hidden attribute on the container for the accordion content whenever the accordion is collapsed. Using CSS to hide collapsed accordion content does not guarantee that it will be hidden from screen reader users, so we recommend using the hidden attribute rather than other CSS tricks.
Article continued below.
Stay on top of web accessibility news and best practices.
Join our email list to get notified of changes to website accessibility laws, WordPress accessibility resources, and accessibility webinar invitations in your inbox.
Nice to Have, But Not Required
There are some additional elements that can be helpful for making your accordions accessible but that are not strictly required by Web Content Accessibility Guidelines (WCAG). You’ll want to determine if these make sense for your particular use case as you’re coding accordions.
ARIA region role and label for the content container
Adding role="region" and an aria-labelledby attribute referencing the open/close button can enhance the accessibility of the accordion content. This can provide additional information about the content container when screen reader users enter it.
If your accordions contain a large amount of content or multiple paragraphs and lists, etc., this extra information may help them to know they are still within the accordion content as they listen to it being read out. If your accordion contains a short paragraph, however, this may add unnecessary noise and can be safely omitted.
List markup
Wrapping your accordions in an unordered list (<ul> and <li> tags) may be helpful for screen reader users, particularly if there are a large number of accordions or multiple groups of accordions on a page.
Using list markup will communicate the number of accordions in a group to screen reader users, which can be helpful information. Learn more about how lists help accessibility on our podcast.
Note, if you add list markup, you only want to have it output if there is more than one accordion in a group. If there is only one accordion, then list markup is not appropriate (no one needs to hear “list, one item”).
Example Code for Accessible Accordions
Here is an example of HTML, CSS, and JavaScript for coding accessible accordions, where the accordions are H3’s following an H2 section heading.
See the Pen Accessible Accordion Example by Equalize Digital (@equalizedigital) on CodePen.
This example is conformant with WCAG 2.2 AA, as required by many accessibility laws around the world. It also conforms to U.S. Web Design Standards and how accordions are expected to be coded on government websites in the United States.
See and edit Accessible Accordion Example on CodePen.
Need help?
Have questions about making your accordions accessible? We offer accessibility audits and remediation plans that help you make your website or WordPress plugin more accessible, as well as one-off consulting engagements. Contact us to get started today.
