Learn Measure Blog About

[role]s do not have all required [aria-*] attributes

Updated

Users of screen readers and other assistive technologies need information about the behavior and purpose of controls on your web page. Native 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.)

Some ARIA roles have required aria-* attributes that provide essential information about state and functionality. For example, the option role requires the aria-selected attribute. If ARIA roles don't have the required attributes, assistive technology users won't be able to successfully interact with them.

How Lighthouse identifies missing required states and properties

Lighthouse flags ARIA roles that don't have the required states and properties:

Lighthouse audit showing ARIA role missing required states and properties

Lighthouse uses the role definitions from the WAI-ARIA specification to check for a role's required attributes. A page fails this audit when it contains a role that's missing its required states or properties.

A missing required attribute won't break the element's role. In the example above, the element is still announced as a heading and assigned a default level of 2. 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 add missing states and properties to ARIA roles

Refer to the WAI-ARIA role definitions to see what states and properties are required for the roles on your page.

Since properties don't change, you can simply add them to the elements that Lighthouse flagged.

States, however, do change as the user interacts with your page, so you'll need to add JavaScript to change the state value when the relevant event occurs. For example, an option role's aria-selected state should toggle between true and false when the user clicks the element or presses Enter or Space when the element is focused.

Resources

Last updated: Improve article