The HTML aria-roledescription attribute
The aria-roledescription attribute sets a human-readable role name, such as slide in place of group. It changes how the role is presented, not what the role is. Limit it to non-interactive containers and more specific widget descriptions, and avoid it when you can.
Overview
The aria-roledescription attribute defines a human-readable, author-localized description for the role of an element. Some assistive technologies, such as screen readers, present an element's role, and this value is what they should use for it. The element's real role stays the same.
Its use should stay limited to clarifying the purpose of a non-interactive container, such as a group or region, or to describing a widget more specifically.
The element should also have a valid role, explicit or implicit, and the value should hold real text, not an empty or whitespace-only string.
The rule is firmer on the generic role, where the attribute is prohibited, and WAI-ARIA says authors must not specify a prohibited property. That covers a plain <div> or <span>, and a <section> with no name, whose role is also generic.
The browser rules differ between versions. WAI-ARIA 1.2 says browsers must not expose an empty or whitespace-only value, while the 1.3 draft says "undefined or the empty string". Chrome and Firefox both keep a whitespace-only value, and on a plain div only Firefox keeps any value.
Syntax
<section aria-roledescription="slide" aria-labelledby="t1">
<h2 id="t1">Quarterly report</h2>
</section>Values
| Value |
|---|
| A string. |
Example
<p>Go to the next slide, then switch the language.</p>
<section id="slide" lang="en" aria-roledescription="slide" aria-labelledby="title">
<h2 id="title">Quarterly report</h2>
</section>
<button id="next" type="button">Next slide</button>
<button id="language" type="button">Spanish</button>
<p role="status" id="out"></p>
<script>
const copy = {
en: { role: 'slide', titles: ['Quarterly report', 'Next steps'], other: 'Spanish' },
es: { role: 'diapositiva', titles: ['Informe trimestral', 'Siguientes pasos'], other: 'English' }
};
const slide = document.getElementById('slide');
let lang = 'en';
let index = 0;
function show() {
slide.lang = lang;
slide.setAttribute('aria-roledescription', copy[lang].role);
document.getElementById('title').textContent = copy[lang].titles[index];
document.getElementById('language').textContent = copy[lang].other;
document.getElementById('out').textContent = 'aria-roledescription is ' + copy[lang].role + ', and the role is still region.';
}
document.getElementById('next').addEventListener('click', function () {
index = index === 0 ? 1 : 0;
show();
});
document.getElementById('language').addEventListener('click', function () {
lang = lang === 'en' ? 'es' : 'en';
show();
});
show();
</script>Best practices
- Reach for
aria-roledescriptionlast. Misuse may make it harder for users to understand or interact with an element, and the interaction can often be broken into pieces that have relevant roles. - Leave the role word out of the accessible name, so a slide is labeled Quarterly report rather than Quarterly report slide.
- Choose widget descriptions that keep the control recognizable. A value like download button still says button, while a bare word like escape hides what the control is.
- If no role fits, use
role="application"with a localized role name. Some assistive technologies reach only focusable elements there, so tie static text to one, for example with aria-describedby.
