Role descriptions need a role that supports them

• Rule: axe/aria-roledescription
• Checks: aria-roledescription must be on elements with a semantic role
• WCAG: 4.1.2
• Fix class: mechanical: A fix needs no authored text or visual decision.

Who it affects

• People who use a screen reader or a braille display, most of them blind.

How to fix it

An element with no role, such as a plain <div> or <span>, has aria-roledescription

Give the element a role that fits it, such as group, region or article, or use the matching element. ARIA prohibits a role description on an element with no role, and browsers drop it.

<div role="group" aria-roledescription="slide" aria-label="2 of 5">
  <img src="harbor.jpg" alt="Boats moored in the harbor at dusk">
</div>

The element has role="presentation" or role="none"

Remove aria-roledescription, since a presentational element has no role to describe. If the element needs a role, give it one in place of none.

axe asks for review because the role is not a button, image, checkbox, radio button, combobox or checkable menu item

Test the element with the screen readers you support and confirm they speak the description. Where one does not, make sure the name alone still makes the element clear.

Fixes that fail

Putting instructions or a label in aria-roledescription, such as aria-roledescription="Press Enter to open"

The value replaces the role screen readers announce, so people lose the role, and the interaction it implies, and hear instructions in its place. Put instructions in visible text or aria-describedby.

Renaming a standard widget role, such as aria-roledescription="item" on a button

People rely on hearing “button” or “checkbox” to know how to operate an element. An unfamiliar word hides that.

More on the rule

axe-core’s documentation of the rule

CORA’s fix guidance adapts content from accessibility-agents, under the MIT License: see its notice.