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
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-roledescriptionproperty gives authors the ability to override how assistive technologies localize and express the name of a role. Thus inappropriately using
aria-roledescriptionmay inhibit users’ ability to understand or interact with an element. Authors SHOULD limit use of
aria-roledescriptionto clarifying the purpose of non-interactive container roles like
region, or to providing a more specific description of a
aria-roledescription, authors SHOULD also ensure that:
- The element to which
aria-roledescriptionis applied has a valid WAI-ARIA role or has an implicit WAI-ARIA role semantic.
- The value of
aria-roledescriptionis 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
Every time I see
aria-roledescription in the wild, it is to offer hint text. Something like this:
<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
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
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
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!
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.
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
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.
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,
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?
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:
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!
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"> family_reunion.jpg </button>
I replicated the button text into the
aria-labelalong with the value I had in the
aria-roledescription(I excluded “button” since that will be announced by default) and dumped
aria-roledescriptioncompletely. 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:
<button> family_reunion.jpg <span class="visually-hidden"> attachment </span> </button>
aria-labelledbyif 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"> attachment </span> <button id="Pic01" aria-labelledby="Pic01 RoleDesc"> family_reunion.jpg </button>
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 ?
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
<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.