Roles need to be valid ARIA roles

• Rule: axe/aria-roles
• Checks: ARIA roles used must conform to valid values
• 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.
• People who control the page by speaking.

How to fix it

The role is misspelled or invented, such as role="buton" or role="dropdown"

Use the ARIA role that matches what the element does, or better, the native element with that role, such as <button> or <select>. Browsers ignore an unknown role, so the element currently has only its native meaning, or none.

The role is abstract, such as widget, landmark, input, section or command

Abstract roles only organize ARIA’s categories; assistive technology does not recognize them on elements. Pick the concrete element or role you mean: <nav> rather than landmark, an <input> rather than input, a named <section> rather than section.

The role is a styling or script hook, such as role="icon" or role="card"

Move the value to a class or a data- attribute, and give the element a real role only if it needs one. For an icon that carries meaning, use role="img" with aria-label; for a decorative one, aria-hidden="true".

<span class="icon icon-warning" role="img" aria-label="Warning"></span>

Fixes that fail

Deleting the invalid role from an element that acts as a control

The rule passes, but the control still has no role, so screen readers and voice control cannot tell what it is. Give it the right element or role.

Correcting the role in the markup without updating scripts and styles

Code that selects on the old value, such as [role="dropdown"], stops matching, which can break the widget’s behavior. Update every selector in the same change.

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.