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.)
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 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.
aria-selected state should toggle between
false when the user clicks the element or presses
Space when the element is focused.
- Source code for
[role]s do not have all required
- Required ARIA attributes must be provided (Deque University)
- Role definitions from the WAI-ARIA specification