All rules

Sheath rule

a11y-no-invalid-role

ARIA role values must be valid.
Package
Core
Category
Accessibility
Default severity
error by default
Auto-fix
Auto-fix available

(dangerous, when no concrete role remains)

#Why

ARIA roles must be valid values from the WAI-ARIA specification. Invalid roles are ignored by assistive technologies, which can cause accessibility issues. Using invalid roles may also indicate a misunderstanding of the intended semantics.

#Examples

#Bad

<!-- Typos in role names -->

<div role="buttn">Click me</div>

<div role="navagation">Menu</div>



<!-- Made-up roles -->

<div role="card">Content</div>

<div role="container">Wrapper</div>

<div role="wrapper">Content</div>

#Good

<!-- Valid ARIA roles -->

<div role="button">Click me</div>

<div role="navigation">Menu</div>

<div role="region" aria-label="Main content">Content</div>



<!-- Landmark roles -->

<div role="banner">Header</div>

<div role="main">Main content</div>

<div role="contentinfo">Footer</div>



<!-- Widget roles -->

<div role="tablist">

    <div role="tab">Tab 1</div>

    <div role="tabpanel">Content 1</div>

</div>



<!-- Draft roles WAI-ARIA 1.3 adds, and both names for the one it renames -->

<svg role="image" aria-label="Sales for 2025"><path d="M1 1" /></svg>

<svg role="img" aria-label="Sales for 2025"><path d="M1 1" /></svg>

<div role="comment">Nice work</div>



<!-- Unknown tokens may precede a supported fallback role -->

<div role="future-role button">Click me</div>

#Which ARIA Version

Accepted roles include every concrete role in the WAI-ARIA 1.2 Recommendation and the concrete roles currently defined by the WAI-ARIA 1.3 Working Draft. WAI-ARIA 1.3 is not yet a W3C Recommendation, and user agents may not support every draft role.

Draft ARIA 1.3 roles such as image, comment, suggestion, sectionheader, sectionfooter, and the associationlist family are therefore accepted. So are the names they replace: ARIA 1.3 renames img to image, and img remains part of the stable 1.2 role set, so neither is reported.

There is no Recommendation-only mode. A passing result establishes that a role belongs to one of the accepted specification sets; it does not establish browser or assistive-technology support for a draft role.

Deprecated is not the same as invalid. directory is discouraged in favor of list, but it is a real role and is accepted.

The role attribute is an ordered fallback list. When at least one concrete supported role token is present, unknown tokens are left in place so newer user agents can use them and older user agents can fall back to the supported role. An attribute made entirely of unknown tokens is reported.

#Valid Roles (Partial List)

#Landmark Roles

banner, complementary, contentinfo, form, main, navigation, region, search

#Widget Roles

alert, button, checkbox, dialog, link, listbox, menu, menuitem, option, progressbar, radio, slider, switch, tab, tabpanel, textbox, tooltip

#Document Structure Roles

article, cell, columnheader, grid, gridcell, group, heading, image, img, list, listitem, row, rowgroup, rowheader, table, term

#Live Region Roles

alert, log, marquee, status, timer

#Notes

  • A native <button> brings the role, keyboard behavior and focus handling that role="button" only declares
  • Check spelling of role names carefully
  • Role matching is ASCII case-insensitive. Lowercase remains the conventional and recommended spelling.
  • See the WAI-ARIA 1.2 Recommendation and WAI-ARIA 1.3 Working Draft for the corresponding role definitions

#References

#Related Rules