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
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
Like all ARIA attributes, aria-expanded doesn’t actually change how elements function. It simply provides additional information for screen readers and other AT.
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.
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.
- 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.
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.