aria-allowed-role
Web validation
role attribute should only contain values that are permitted for the element.WAI-ARIA roles define the meaning and behavior of HTML elements, but not every role can be applied to every element. The ARIA in HTML specification sets out which combinations are valid. Assigning a disallowed role doesn't make browsers or assistive technology treat the element as that role. Instead, assistive technology may ignore it or report it incorrectly, which can confuse people who rely on screen readers or other assistive technology.
Pass Patterns
A <div> used as a modal dialog
The <div> element supports the dialog role, so the combination is valid.
<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
<h2 id="dialog-title">Subscribe to Updates</h2>
<p>Enter your email:</p>
<input type="email" />
<button>Send</button>
</div>A search form
The <form> element is allowed to adopt the search landmark role.
<form role="search" action="/search">
<label for="q">Search the site</label>
<input id="q" name="q" type="search" />
</form>Fail Patterns
A <header> pretending to be a button
The <header> element is structural, so the button role is not allowed here.
<header role="button">
Company Header
</header>A heading declared as a button
Heading elements cannot take the button role.
<h2 role="button">Show details</h2>Try It Yourself
Explore the specification
For the full list of allowed HTML element and ARIA role combinations, refer to the ARIA in HTML specification > Document conformance requirements for use of ARIA attributes in HTML > Rules of ARIA attribute usage by HTML element table.
Inspecting the browser dev-tools
- Open your browser's dev tools and select the element in the Elements panel.
- Note the element's tag name and the value of its
roleattribute. - Check the ARIA in HTML table to confirm the role is allowed for that element.
- In the Accessibility panel, check the Role that the browser exposes.
Expected results: The role is allowed for the element, and the Accessibility panel shows the intended role.
Actual results: The role is not allowed for the element, and the Accessibility panel shows a different role than intended, or the role is ignored.
FAQ
Why is this rule considered a best practice?
WCAG requires correct semantics but does not explicitly outlaw every invalid role pairing. However, invalid pairings can cause assistive technologies to ignore or misreport roles, so following this rule keeps role assignments predictable and helps assistive technology report elements correctly.
Why is this issue marked as Minor?
An incorrect role seldom blocks the user outright as native semantics usually remain. The issue can still mislead users or tools, so fixing it improves consistency without typically causing critical barriers.