The aria-expanded attribute fulfills a purpose that is not currently available in HTML. It describes whether a focusable, interactive element is expanded or not expanded.
Importantly, aria-expanded also tells users that an element is capable of being expanded or collapsed. Without this information, people who use assistive technologies (AT) may not be able to discover that functionality.
You can use the aria-expanded state for any expandable or collapsible region, provided that the region expands without refreshing the page. For example:
- Expandable menu bars with links
- Paragraphs of text that are only visible when the user clicks a button
- Autocomplete elements on form entries
- Dialog widgets
Aria-expanded is especially useful because it allows developers to provide feedback to users after an element is activated. Through JavaScript, the aria-expanded value can be changed after activation — and screen readers will announce the change, enabling the user to navigate to the content they want.
However, as with all ARIA attributes, misusing aria-expanded can create accessibility barriers. For accessibility, a website without ARIA is better than a website with bad ARIA.
Before writing markup, we strongly recommend reading about common ARIA mistakes. You’ll also need to test your ARIA implementation thoroughly (we’ll discuss best practices for testing later in this article).
Related: 4 Questions to Ask Before Using ARIA
Understanding Aria-Expanded
Like all ARIA attributes, aria-expanded doesn’t actually change how elements function. It simply provides additional information for screen readers and other AT.
Here’s a simple example of aria-expanded without JavaScript. In practice, most uses of this state will use JavaScript to send the correct value (true if the element is expanded and false if the element is not expanded).
<button aria-expanded="false">
Read more
</button>
Screen readers may announce something like: “Read more. Button collapsed.” When the user clicks the button, JavaScript will change the aria-expanded value to true, and the screen reader will announce that the content is expanded.
Different screen readers may output information in different ways. It’s a good idea to download a free screen reader like NVDA (NonVisual Desktop Access) or use your operating system’s built-in screen reader to review your content.
Related: 5 Myths About Screen Readers That Can Hurt Accessibility
Common Problems with Aria-Expanded
aria-expanded is an example of an ARIA attribute that is appropriate for general use — most modern websites have menu bars, expandable text, and similar elements, and plain HTML doesn’t have the semantics to describe the state of these elements to assistive technology users.
Some tips for avoiding common mistakes:
- aria-expanded should be used when a control triggers a change without refreshing the page. If the change causes the page to refresh, don’t use aria-expanded.
- Since aria-expanded indicates control, don’t use it on elements that do not control the expanded state of other elements.
- Don’t write custom values for aria-expanded. The attribute can only be true, false, or unidentified.
- Make sure your element has the correct default value. For example, if the element is collapsed by default, make sure the default value is aria-expanded="false" and make sure your JavaScript changes the value to true when the element expands.
- Only use aria-expanded with supported roles. For a full list of supported roles, review the World Wide Web Consortium (W3C)’s aria-expanded wiki page.
When testing ARIA markup, don’t rely on automated tools alone
Automated accessibility tests can be extremely useful for finding hundreds of potential barriers. With that said, even the best tools available have significant limitations, particularly when evaluating ARIA markup.
To an automated tool, the aria-expanded state may appear correct, despite having an inaccurate default value — and in some cases, ARIA may be completely unnecessary to achieve a certain presentation (which means you should avoid using it).
You can test your ARIA markup manually by downloading a screen reader and accessing your page. However, if you don’t have significant experience with screen readers, you may not find every accessibility barrier, and you might spend time remediating “problems" that wouldn’t affect the real-life experience of an experienced AT user.
Related: Is Automated Testing Enough for Accessibility Compliance?
Work with an accessibility partner to avoid ARIA mistakes
The Bureau of Internet Accessibility provides resources to help developers create better content. To discuss your ARIA implementation or for guidance with any web accessibility issues, send us a message to connect with a subject matter expert.
For an overview of your website’s current level of accessibility, start with our free website analysis, which tests your content against Web Content Accessibility Guidelines (WCAG) 2.1 Level AA checkpoints.
