[aria-*] attributes do not match their roles

[aria-*] attributes do not match their roles

Appears in: Accessibility audits

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.)

Each 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 aria-* attributes:

Lighthouse audit showing an ARIA list role with an unsupported checked attribute

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.

The Lighthouse Accessibility score is a weighted average of all the accessibility audits. See the Lighthouse accessibility scoring post for more information.

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.

Resources #

Last updated: Improve article