Users of screen readers and other assistive technologies need information about the behavior and purpose of controls on your web page. Built-in HTML controls like buttons and radio groups come with that information built in. For custom controls you create, however, you must provide the information with ARIA roles and attributes. (Learn more in the Introduction to ARIA.)
role supports a specific subset of
aria-* attributes. Applying an attribute to a role that doesn't support it generally won't break the role, but it should still be fixed.
How Lighthouse identifies ARIA mismatches #
Lighthouse flags mismatches between ARIA roles and
Lighthouse uses the role definitions from the WAI-ARIA specification to check for mismatches between ARIA roles and attributes. Each role has a set of states and properties (that is, attributes) that it can support or inherit. A page fails this audit when it contains an element with an ARIA role and an ARIA attribute that isn't supported for that role.
In the example shown in the screenshot, the
aria-checked attribute is not allowed on an element with the
list role. This makes sense: list elements can't be checked or unchecked.
An unsupported attribute generally won't break an element's role. In the example above, the element is still announced as a list, and the browser ignores the
aria-checked attribute. However, this issue is still important to fix and probably indicates a mistaken assumption in your code.
How to avoid ARIA mismatches #
Refer to the WAI-ARIA role definitions. ARIA explicitly defines which attributes are allowed for each role. As long as an attribute is listed for the role you're using, you can apply it.
- Source code for
[aria-*]attributes do not match their roles audit
- Elements must only use allowed ARIA attributes (Deque University)
- Role definitions from the WAI-ARIA specification