Avoid aria-roledescription

HTML has all sorts of built-in features that, when used correctly, are accessible, will localize, and which just work. For example, if I want a button, I use <button>, and a screen reader will announce it as button. For users in other languages, they will hear whatever is their word for button.

For cases where HTML does not have the control built in, ARIA can be used to fill that gap. If you want a tabbed interface, for example, you can use the tab, tablist, and tabpanel roles. A screen reader will announce those components for users in their own language through no additional effort on your part.

A New Property

ARIA 1.1 introduced a new property: aria-roledescription

Defines a human-readable, author-localized description for the role of an element.

[…]

The aria-roledescription property gives authors the ability to override how assistive technologies localize and express the name of a role. Thus inappropriately using aria-roledescription may inhibit users’ ability to understand or interact with an element. Authors SHOULD limit use of aria-roledescription to clarifying the purpose of non-interactive container roles like group or region, or to providing a more specific description of a widget.

When using aria-roledescription, authors SHOULD also ensure that:

1. The element to which aria-roledescription is applied has a valid WAI-ARIA role or has an implicit WAI-ARIA role semantic.
2. The value of aria-roledescription is not empty or does not contain only whitespace characters.

To summarize: this property allows an author to override what role is announced to a screen reader user. There is some guidance: no blank values, only use it on things that already have implicit or explicit roles, and use it only to clarify a thing.

Do Not Do This

There are reasons to be careful with aria-roledescription.

Hints

Every time I see aria-roledescription in the wild, it is to offer hint text. Something like this:

<label for="Foo">Phone</label>
<input type="text" id="Foo" aria-roledescription="Only numbers are allowed">

This developer has effectively told the screen reader that instead of announcing input type in text to replace it and say Only numbers are allowed.

There is no HTML element by that name. There is no ARIA widget by that name. It is meaningless and hides the control type. Is it a text input? A number input? A calendar widget? A range slider?

This happens enough with aria-roledescription that there is an open issue about using it for hint text in the ARIA spec.

Verbosity

The ARIA 1.1 spec is clear that the value from aria-roledescription overrides the native role. The spec offers an example of adding the original role into the aria-roledescription to provide interaction guidance to users:

<button aria-roledescription="attachment button">
  family_reunion.jpg
</button>

This makes sense when you want to qualify the kind of a control in the context of a specific use. Support in browsers and screen readers suggests this is probably the safest approach.

But right now, a screen reader is just as likely to also announce the role as the aria-roledescription value. In JAWS on Chrome, for example, that button is announced as attachment button button.

Because of the misuse I outlined with hints, there is an open issue to make the extra announcement standard.

Localization

Today your native and ARIA controls are announced in whatever language the user speaks. If the user has their screen reader and browser in Portuguese, they will hear <button> announced as botão.

Once you override its role with aria-roledescription, they will hear it in whatever language you provided. There is no auto-translation. We already know you cannot rely on aria-label to auto translate, but it definitely will not with aria-roledescription.

That attachment button will sound like attachment button botão to our Portuguese JAWS user (and with a Portuguese pronunciation on all the words). Here is sort of an inverse example:

<button lang="pt" aria-roledescription="meu berimbau botão">
  Jogar
</button>

When you use aria-roledescription you are freezing that widget or region to one language. That means you have to fold this node into your localization workflow. To presume that your screen will only be used by, say, Americans who speak English is the height of hubris considering how many Americans only speak English as their second language.

Preferences

One of my biggest fears is that someone somewhere decides that the way assorted screen readers announce the same control differently is enough of concern that they will want to standardize the end user experience to their own preferences or experience.

Do you find it weird that JAWS and NVDA call a <select> a combobox while VoiceOver and TalkBack call it a pop-up button? Does your team refer to everything that alternates between hidden and visible as a drop-down, regardless of how it functions? Have I got a trick for you!

<select aria-roledescription="dropdown">
 […]
</select>

This is not an irrational fear dreamt up from nowhere. I have met people in QA roles who cannot abide the different names for <select> when testing because it does not match the story or script or spec or whatever artificial document they have.

Maybe a Use Case?

If you have a very specific audience, that is homogeneous in language, in skill, in experience, and in technology, and that audience has struggled with a specific concept or control, then sure, maybe experiment.

The ARIA 1.1 spec gives a couple reasonable examples, such as a button to download an attachment or a slide in a carousel.

You could add it to a wrapper to make a set of disconnected widgets present as a contiguous whole. Though if you are only doing it to convey a visual concept that blind screen reader users care little about, skip it. Further, an interesting feature in JAWS is to ignore the aria-roledescription on the region, but override the nested controls instead (see the accordion example below).

Perhaps you create a completely novel interface using canvas for a specific set of users that you can train and prepare. In that highly specific scenario, sure? Give it a shot and test it with your users?

Maybe you find a button with aria-pressed or a checkbox is not sufficiently clear to users as a toggle. In that case it might be worth experimenting with it, making sure that if it matches a platform native control that your co-opted version behaves in exactly the same way:

<button aria-pressed="false" aria-roledescription="toggle">
  Wifi
</button>
<button aria-pressed="false" aria-roledescription="switch">
  Bluetooth
</button>

Either way, if you only ever approach aria-roledescription as an option worth testing to remedy a documented problem, then you may be in good shape.

Examples

I made a pen with the above examples that you can try with your preferred screen reader and browser combination. When I have time later I will record some of the output and add it. In the meantime, visit the pen in debug mode or play with it below.

See the Pen QWjMPgV by Adrian Roselli (@aardrian) on CodePen.

Videos

Wrap-up

My experience with aria-roledescription so far is that it is code smell for accessibility problems. The WebAIM Million report bears this out. The First Rule of ARIA supports this.

You think you may have found a use case, and you may argue passionately for it. Until you get it in front of your users, it is nothing but a potential for technical debt and poor user experience.

Regardless, if the mis-use continues and screen readers are forced to override specified behavior as a result, you can expect this attribute to be deprecated in the future. In my opinion, that may be the best outcome given where we are today.

Update: 7 August 2020

Owing to a known JAWS bug along with varying support elsewhere, Steve has found a valid use for aria-roledescription:

Tested codepen.io/stevef/pen/ExjbJWv in latest Chrome/Firefox/Edge with JAWS/NVDA
all 3 Browsers expose it as a heading without a level
JAWS treats heading without a level as a <h2>
NVDA just as a heading without a level
Added aria-roledescription to some see what happens

This approach effectively makes role="doc-subtitle" something you can use today, as opposed to <hgroup>, which has no support, was deprecated in the W3C HTML specification, yet persists in the WHATWG HTML specification (with ongoing arguments to make it actually do something).

Update: 6 October 2020

Steve is back with micro-note on aria-roledescription, this time showing it is not the correct method for identifying a fascist.

Update: 19 April 2022

I was working on a thing and went back to test some known aria-roledescription bugs in JAWS. These two appear to still be bugs in JAWS 2021:

• #407 JAWS doesn’t narrates element role inside group with aria-roledescription, 17 July 2020
• #510 Role BUTTON is not announced with Virtual PC Cursor inside container with aria-roledescription, 18 March 2021

This one appears to no longer be an issue, with or without the accessible name on the container:

• #288 aria-roledescription overrides semantic roles of descendant elements, 4 September 2019

As of this writing I am not running the latest JAWS, however. Granted, plenty of users are not either.