aria-allowed-role
Explicit role must be permitted for its host element
Checks that an explicit role="" attribute is one of the roles the ARIA-in-HTML specification permits for the host element (e.g. role="tab" is not permitted on <nav>).
Applies to. Applies to elements with an explicit, valid, non-abstract role, where the host element/attribute combination has an asserted permitted-roles constraint in the ARIA in HTML specification's table of permitted roles.
Expectation. The explicit role is one of the roles the ARIA-in-HTML specification permits for that host element. Reported at CANTTELL rather than FAIL: ARIA-in-HTML's permitted-roles table is an author conformance requirement with no ACT rule and no WCAG mapping in any source. The role the author asked for is still the role assistive technology exposes, so whether the combination harms anyone depends on the widget, not on the table.
What a finding reports.
role: the explicit role that is not permitted on the host element.
These data.details fields help to read and reproduce a finding. Apart from reasonCode and the few fields Output schema names as stable, they are not a stable contract: a field may be renamed or dropped in a minor release, so don’t build on them.
Examples
<nav role="navigation">...</nav>
role="navigation" is permitted on <nav> by the ARIA-in-HTML spec (it's also the element's implicit role).
<nav role="tab">...</nav>
role="tab" is not one of the roles ARIA-in-HTML permits on <nav>.
How to check
When this rule can’t decide, it reports cantTell and leaves the question to a person. Each question it can ask is listed here under its reason code, with the steps to answer it. A finding carries the same steps as howToCheck, in the scan’s language. See Output schema.
ARIA_ROLE_NOT_ALLOWED_FOR_ELEMENT
- Inspect the element the report names and note its tag and its role attribute.
- Open the Accessibility pane in the browser's developer tools and check which role is exposed.
- Press Tab to see whether the element takes keyboard focus, and try operating it with Enter or Space if it is a control.
- With a screen reader, move to the element and compare what is announced with what the element does on screen.
Pass. The announced role matches how the element looks and behaves (or role none/presentation was ignored on a focusable control and its native role is kept).
Fail. The announced role contradicts the element's behaviour, such as a focusable button announced as a heading, which fails ARIA in HTML and can fail WCAG 4.1.2.