Accessible Accordions

✋Raise your hand if you include accordions on almost every website you build.

Accordions are helpful for shortening long pages and allowing people to scan headings quickly, then expand them to get additional information. But if the accordions on your site are not built accessibly, then users of assistive technology may miss out on the information included in the accordions completely.

When it comes to FAQs, for example, content is almost exclusively presented in accordions. How frustrating would it be to visit an FAQ page and hear all the questions but not be able to access the answers?

Read on for more information on how to ensure your accordions don’t leave your users in the dark.

How to Tell if an Accordion is Accessible

There are two ways to tell if an accordion is accessible:

1. Test it with your keyboard to ensure you can open and close the accordion without using a mouse.
2. Listen to the accordion with a screen reader to ensure it conveys information about what it is and its opened or closed state to blind and visually impaired users.

Of the WordPress plugins out there, some fail on the first check, and their accordions cannot be used without a mouse. A more significant percentage work with a keyboard but are not appropriately labeled for screen readers, making them confusing or impossible to use without sight. Because of this, it’s essential to test accordions with a screen reader like VoiceOver or NVDA, not just test them with a keyboard.

Anatomy of Accessible Accordions

When you’re testing accordions for accessibility, here is what you want to see:

Proper heading and button markup

The label or text that controls the accordion opening and closing should be wrapped in a button tag within a heading tag of the correct heading level.

Using a heading is crucial because it allows screen reader users to jump to the accordion they’re most interested in and lays out the content meaningfully for both people and search engines.

ARIA on the button

The button should have an aria-expanded attribute on it to indicate if it is opened or closed and aria-controls that indicate what element the accordion button controls.

Here’s example code for an accordion heading:

<h3>
<button aria-expanded="false" class="accordion-title" aria-controls="answer1" id="accordion1id">How do you make an accessible accordion? </button>
</h3>

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.

ARIA on the content container

The container with the content for the accordion also needs ARIA added to it to help screen reader users know what it is. Adding role=”region” and an aria-labelledby attribute that links back to the button helps screen reader users to know when they’re entering the content container and connects it with the button.

Here’s an example of code that would go with the accordion heading above:

<div id="answer1" role="region" aria-labelledby="accordion1id" class="accordion-panel">
<p>Read this article and you’ll know how.</p>
</div>

Accessibility for sighted users

For people who can see, you’ll want to make sure that there are clear focus indicators and that everything in the accordion passes color contrast checks.

Also, don’t use accordions or turn on settings that automatically collapse accordions when a new one is opened. This can be a very disruptive experience for users as the page can visually scroll, or they may lose the content they were trying to read if a very large accordion is closed and the content below it all shifts up. Allow users the choice to collapse accordions or to leave them all open.

Icon considerations

Adding icons such as up and down arrows or plus and minus symbols is a typical design accent on accordions. These icons can be beneficial in helping people to recognize that the accordion title can be interacted with.

If adding icons, make sure there is only one tab stop on the button that opens and closes the accordion (not one for the text and one for the icon) and make sure that the icon has empty alt text or aria-hidden on it so it will not be announced to screen reader users.

WordPress Accordion Plugins

Most WordPress accordion plugins and accordions in page builders have accessibility issues.

Common problems

Across the six accordion plugins and three builders I tested, common accessibility issues include:

• Setting focus outlines to none.
• Not using headings.
• Using headings but not allowing the user to define the level, which would result in headings being out of order.
• Using links instead of buttons to open and close the accordion.
• Not hiding decorative icons from screen readers.
• Missing ARIA attributes.
• Marking accordions up like tabs (but not accessible tabs).

Possible options

The block editor accordion plugin that did the best with accessibility in my tests is Accordion Blocks.

This plugin sounds good on a screen reader and works with a keyboard only; the only downside to it is that the developer has added a role of button on the heading that opens and closes the accordion, like this:

<h3 id="at-620" class="c-accordion__title js-accordion-controller" role="button" tabindex="0" aria-controls="ac-620" aria-expanded="false">This is an accordion title</h3>

When a different role is added to a heading, it no longer appears in the heading list within screen readers. If you use this plugin, you may want to add the same heading within the accordion panel to ensure it appears in the headings list.

Another option that generally looked good, but was also missing the heading structure, was the accordion block in Kadence Blocks. This plugin uses buttons to open and close the accordions and has correct ARIA attributes.

Either of these plugins might be a good starting point for accordions on your websites. If you’re using a different accordion plugin, take a second look at it.

Build Your Own

Want to build your own accordion or see a detailed code example of an accessible accordion? Check out this accordion example in the W3C’s ARIA Authoring Practices Guide.