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.


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.


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">

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.


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">

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.


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">

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">
<button aria-pressed="false" aria-roledescription="switch">

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.


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.


Running Firefox 76.0 and NVDA 2019.3.1 on Windows 10. You can hear each control with its aria-roledescription overriding the native control name, including the link (which I do not reference above). Pay attention to how it announces the accordion region. You also can tell I do not have a Portuguese language pack installed.
Running Chrome 81.0.4044.129 and JAWS 2018.1808.10 on Windows 10. The missing spaces in the captions are intentional. The accessible name and aria-roledescription values are sometimes concatenated. You can hear this most clearly on the <select> where JAWS inserts an extra syllable between the two words. You can also hear the link is not changed (but is mis-announced because of this accName bug in Chrome), and all the buttons in the accordion have their role over-written even though that is not what the code is doing.
Running Internet Explorer 11 and JAWS 2018.1808.10 on Windows 10. The missing spaces are intentional. You can hear JAWS applies aria-roledescription to the <button>s while also overriding the button role for those in the accordion.
Running Safari and VoiceOver on macOS 10.15.2. You can hear VoiceOver applies the lang attribute to the <button> announcement, but not its aria-roledescription. Text inputs and <button>s with aria-pressed are called both toggle button and checkbox, regardless of the aria-roledescription.
Running Safari and VoiceOver on iPadOS 13.4. For links and text inputs aria-roledescription has inverse support compared to macOS. It also does not switch voices on the Portuguese, does not call the toggles checkboxes, nor recognizes the aria-roledescription on the region. This lack of parity between VoiceOver across platforms can be frustrating for users.
Running TalkBack and Chrome 81.0.4044.117 on Android 10. I paired it with a keyboard to keep the camera from changing focus as I swiped through everything. As you can hear, aria-roledescription is thoroughly ignored (as is the content in the <code> in the link, owing to an unrelated Chrome bug).
Running TalkBack and Firefox 68.7.0 on Android 10. aria-roledescription behaved as with Chrome, though as I tabbed through the page it only did it in reverse (and Shift had no affect). So that was an unrelated but novel discovery new to my set-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:

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:

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

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



If I understand the spec it is not intended for the use in the examples you give. All of them are not legitimate reasons to use them and I agree with you that you should use aria-roledescription in them.

What you do not do is to argue about the examples in the spec. I think using them to provide information to generic roles seems reasonable.

Sadly, you argue again to not use a tool because others incorrectly use it. With that stance we wouldn’t use kitchen knives as you may use it to hurt people.

All the best,

Martin Kutschker; . Permalink
In response to Martin Kutschker. Reply

To your first point, one of the examples I give is from the spec, specifically the download button under the Verbosity heading.

To your second point, see my first point.

To your third point, I provide a potential use case as well as some caveats an organization should keep in mind.

A better analogue might be that the kitchen knives I have now already do their job well. Maybe do not paint them pink, cover them in fun fur, rename them to foodly preparinators on all the packaging, and sell them in toy stores.


Thanks for your article. What do you think about “augmenting”/”annotating” paragraphs for example like this:

  This action is not reversible

Clever trick or misuse?

mr.fusion; . Permalink
In response to mr.fusion. Reply

Misuse. A paragraph is not an interactive control, a widget, nor a region. Annotating is the same as hint text, which I outline in my post.


Just FYI, you’ve got a broken link/malformed HTML in the section A New Property:

<a href=https://www.w3.org/TR/wai-aria-1.1/"#widget"><code>widget</code></a>

J. Redhead; . Permalink
In response to J. Redhead. Reply

Fixed. Thanks!


What are your thoughts of using aria-label to have role description + label together? At least the translation would work in more tools…

P.s. Once again, thanks for your blogpost!

In response to Sandrina Pereira. Reply

You risk having a verbose accName and you must replicate the text content into the aria-label (which creates extra surface for errors), arguably violating the First Rule of ARIA. Using the Verbosity example and adjusting it as you suggest:

<button aria-label="family_reunion.jpg attachment">

I replicated the button text into the aria-label along with the value I had in the aria-roledescription (I excluded “button” since that will be announced by default) and dumped aria-roledescription completely. As long as the fake role follows the visible text, I would not consider this a 2.5.3 Label in Name failure.

If you find your users benefit from that extra info, then maybe try it with visually-hidden text to reduce the risks:

  <span class="visually-hidden">

Or aria-labelledby if you find ARIA is the better option for other reasons (such as using the values over and over and over, though HTML compresses well so file size is effectively moot as a reason):

<span class="visually-hidden" id="RoleDesc">

<button id="Pic01" aria-labelledby="Pic01 RoleDesc">

hello, what about emails ?
what do you think of adding role=”article” aria-roledescription=”email” to a wrapping container..would that help he user to understand what he reads ?

blobi; . Permalink
In response to blobi. Reply

Almost definitely not. I think if you want the user to understand what they are reading you should use a heading, give it an accName (such as aria-labelledby), or make sure the context is clear. Trying to strip the “article” context could be confusing.

Regardless, if I add aria-roledescription to <article> it has no effect in NVDA or JAWS (with or without an accName). I tested no further than that since it covers 80+% of users.

Leave a Comment or Response

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>