Easy ARIA tip #8: Use aria-roledescription to selectively enhance the user experience

In WAI-ARIA 1.1, the aria-roledescription attribute has been added to give web authors the ability to further describe the function of a widget. Here are a few tips for usage.

The definition of role

When screen readers describe any control or item on a website, they use multiple pieces of information to describe it to the user:

  1. The name or label. What does the element do? “Add a file”, for example.
  2. The role of the item. What kind of control is it? To stick with our example, it’s most probably a button.
  3. For some controls such as checkboxes or radio buttons, toggle buttons etc., the state or states. Am I checked? Am I the selected radio button in a group of radio buttons? Am I pressed?
  4. The description, if present. Further information that might show up as a tool tip when hovering over it with the mouse, or focusing with the keyboard. To stick with our example: “Adds a new file to the current folder”.

1 and 2 should always be present correctly, 3 for the control types that states apply to, and 4 is optional.

So, for a correctly coded widget, and for assistive technologies to use it, 1 and 2 must be correctly set, keyboard interaction implemented etc. For some, web developers must also make sure that the correct states (3) are always applied or changed.

Add aria-roledescription

What aria-roledescription does, in a nutshell, is it tells the screen reader to speak and braille something for item 2 above that is defined by the web developer. For roles, screen readers have a default, localized, set of terms they use to describe items. “Button”, “text field”, “checkbox” are some examples. aria-roledescription overrides the assistive technology’s default role description for an item exposed by the accessibility APIs. This attribute should be used wisely, since it can be the yay or nay for an assistive technology user to understand, or not understand, your user interface.

Here are a few guidelines you as a web developer should follow strictly when considering to use aria-roledescription.

  1. Make sure your widget is understandable without it. Pretend that aria-roledescription doesn’t exist, and make sure your widget or compound widget works with a correct standard role or set of roles first.
  2. If you feel that your UI is understood better with aria-roledescription added, add it, bearing in mind that the string you use is used literally, not being mapped to some ID or numeric value. The raw string you put in there will be passed on to the screen reader. This also means that, if you offer your UI in different languages, make it localizable and offer the localized string for each language. Make clear in the localization notes that this is a string being spoken to blind users to help them understand the widget better.
  3. Make sure you do not take away information. If you want to enhance the description of a button, make sure the fact that this is a button is still in there somewhere, or your users might not know that they need to press Space to activate.

A few examples

These examples by ETS research show good use of the aria-roledescription attribute. The first two are regions that are explicitly declared as slides (like in a PowerPoint or Google Slides presentation), while the other two are good examples of enhancing the button’s description, but still keeping the button semantic clearly audible.

I recently also came across an example in the newly released Open-Xchange OX App Suite 7.10 where a newly introduced window manager and task bar can be enhanced to provide the user with information that this is a special kind of toolbar, namely a task bar. There is no task bar role in either HTML or WAI-ARIA. So what can be done, and what I also suggested to the developers, is to make sure everything works as if this was a normal toolbar, including the appropriate roles, and then enhance the container item that has the role “toolbar” with an aria-description specifying that this is, indeed, a task bar. We’ll see if they add it and if so, how this plays out. 🙂


As with everything in WAI-ARIA, be mindful of using attributes and roles. Think about the impact your choice might have. But if used in the right context, aria-roledescription can be a great enhancement to the user experience. If used wrongly, though, it can also lead to greater inaccessibility of your web application.

Also note that not all combinations of assistive technologies and browsers support aria-roledescription yet. Firefox does, in combination with NVDA at least, and VoiceOver and Safari on macOS are said to have suport as well. Other combinations may or may not have it yet, so it is very important that you follow the advice and make sure your widgets “speak” without it as well.

4 thoughts on “Easy ARIA tip #8: Use aria-roledescription to selectively enhance the user experience”

  1. One worry I have with aria-roledescription is internationalization. Assistive technologies know the standard roles, and can announce the purpose/role of a control to the user in the user’s own language (which may well be different from the language of the page/document). So a control with role=”button” may be announced by a French SR as “bouton”…but if it’s overridden via role description, it will then be announced as “attachment button”. Which may be initially confusing for users.

    1. To build on this, I have seen folks use emoji in code with the awful excuse of getting around localization concerns. I am terrified of the day I see a hamburger menu with the code aria-roledescription=🍔. And if you are reading this and think that is a good idea, please leave your street address so I can egg emoji your house.

  2. of course, there’s also the potential for abuse or simply user confusion. if i’m a “clever” developer and decide to add an aria-roledescription of “hyperdrive activation unit” to a humble button element…will the AT user know what the heck this thing they just landed on is, and more importantly how to operate it? standard roles may be few and limiting, but at least users know full well what to expect and more importantly how to operate things with particular known roles…

Leave a Reply

Your email address will not be published. Required fields are marked *