To create accessible content, you need to clearly define the structure of your content. That’s where WAI-ARIA (Web Accessibility Initiative - Accessible Rich Internet Applications) can be useful.
WAI-ARIA defines web semantics that can’t be applied through native semantic HTML. This allows screen readers and other assistive technologies (AT) to present content in a predictable, operable way.
In ARIA, roles define a type of user interface elements, while states and properties provide additional information about each role. ARIA roles can be powerful, and it’s important to remember the first rule of ARIA: If possible, use native HTML instead.
If you’ve determined that ARIA is the right tool for the job, make sure to avoid common mistakes when writing your markup. Below, we’ll address some of the most common issues — but we strongly recommend working with an accessibility partner to limit potential barriers. For guidance, send us a message to connect with an expert.
1. ARIA roles require correct syntax and spelling
Most ARIA issues occur because of simple spelling and syntax mistakes (that’s also true for pretty much every type of web development issue). For example, role="combobox" is correct, but aria-role=”combobox" is meaningless. Screen readers will fail to announce the combobox.
Some concepts to keep in mind when writing markup:
-
ARIA role values must be lowercase. Otherwise, AT may not recognize or announce them.
-
Make sure you’re using the correct ARIA attribute for the job. For example, aria-label and aria-labelledby behave similarly, but they’re distinct properties.
-
Double-check your spelling. As with HTML, an extra space or incorrect letter can make a big difference.
Related: 5 Common Misconceptions About WAI-ARIA and Accessibility
2. Be careful when copying ARIA markup
Of course, the easiest way to avoid syntax errors is to copy your markup. Nearly every web developer copies from online code depositories and other sources — but copying and pasting ARIA can have unexpected results.
For example, let’s say you copy aria-expanded markup from another page. On the original source, the markup may have the value aria-expanded=”true.” If your element isn’t expanded by default, the correct value would be aria-expanded=”false.”
An automated test may not find errors in your markup. After all, you have working ARIA — but it’s sending precisely the wrong information to actual screen reader users.
The solution: Test your markup regularly, especially if you’re copying and pasting. Ideally, screen reader testing should be performed by people who have years of experience with popular tools like NVDA (NonVisual Desktop Access) and JAWS (Jobs Access With Speech).
Related: How Screen Readers Are Used in Accessibility Testing
3. Don’t invent new ARIA roles
The World Wide Web Consortium (W3C) publishes WAI-ARIA standards, which allow roles to be defined within six established categories.
Those categories include:
-
Abstract roles
-
Widget roles
-
Document structure roles
-
Landmark roles
-
Live region roles
-
Window roles
Each category has defined roles, which you can find in the W3C’s WAI-ARIA 1.1 recommendation. The exception is abstract roles, which are foundational to ARIA standards, but should not be included in content.
You can’t invent a new role, even if you really, really need one — assistive technologies won’t be able to interpret your intention.
Related: What Are the Three Types of ARIA Attributes?
4. Make sure you’ve included required attributes
Certain ARIA roles have expected children, states, and/or properties. If you don’t include those attributes, screen readers may skip the role entirely or output the wrong information.
For example, the menu role predicts the presence of menu items (otherwise, it’s not much of a menu, is it?). The menu must also have an accessible name, which must be included with aria-label or aria-labelledby.
The Mozilla Developer Network (MDN) provides a detailed explanation of each ARIA role and its required attributes.
Related: Don't Use ARIA to Fix Broken Semantics
If you use ARIA, have an accessibility testing strategy in place
WAI-ARIA can improve accessibility, but when misused, it can have the opposite effect. Web developers often use ARIA markup to over-engineer their websites — if you use the wrong attributes or add ARIA to an element that is already defined in HTML, you’re not improving experiences for your users.
We strongly recommend working with an accessibility partner, especially if your content is complex or dynamic. The Bureau of Internet Accessibility can help. To learn about our accessibility testing and remediation services, send us a message.
