Back to Info and Examples for Accessibility Insights for Web

aria-roledescription

The aria-roledescription attribute must be used only on elements with a supported role. This rule has been deprecated for axe-core 4.7.0 release and has been disabled. A revised rule may be released in a future version of axe-core.

Why it matters

The aria-roledescription attribute is used to override how assistive technologies report an element’s role. For example, assistive technologies typically report a <button> element (or a <div> with role="button" ) as a "button". If aria-roledescription="slider button" were added to either element, assistive technologies would report it instead as a "slider button".

Assistive technologies report an element’s role only when the role is semantic (has inherent meaning). For example, they inform users when they encounter links, buttons, or images, but not when they encounter semantically neutral elements, such as <span> or <div> or <p> elements. The aria-roledescription changes only how an element’s role is reported, not necessarily whether it’s reported. An assistive technology might not announce a semantically neutral element, even if it has an aria-roledescription attribute. As a result, people who use assistive technologies might not discover such an element exists.

How to fix

Use aria-roledescription only on elements that have an explicit or implicit ARIA role.

An implicit ARIA role is derived from the element itself. For example, a <button> element has an implicit role of button. For a list of HTML elements and their implicit roles, see ARIA in HTML. (Elements noted as having "No corresponding role" have no implicit ARIA role.)
You can add an explicit ARIA role using the role attribute. For example, adding role="button" to a <div> element changes its role to button.

Example

Fail

This custom control is coded on a semantically neutral <div> element, and no explicit role has been applied. Although scripting (not shown) causes the element to function as a button, assistive technologies might not report the element to users.

<div tabindex="0" aria-roledescription="download button">Download</div>

Pass

An explicit ARIA role is applied using role="button". Assistive technologies announce the element because it has a semantic role. The aria-roledescription attribute instructs assistive technologies to identify the element to users as a "download button."

<div role="button" tabindex="0" aria-roledescription="download button">Download</div>

About this rule

This rule passes if:

aria-roledescription is used on an element with a semantic role

More examples

Understanding Success Criterion 4.1.2: Name, Role, Value

ARIA in HTML