[aria-*] attributes do not have valid values

[aria-*] attributes do not have valid values

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 that define the state and properties of that role. For example, the aria-selected attribute indicates whether an element is currently selected depending on whether its value is true or false.

If an element's ARIA attribute doesn't have a valid value, assistive technologies won't be able to interact with it as the developer intended.

How Lighthouse determines an ARIA attribute's value is invalid #

Lighthouse flags ARIA attributes with invalid values:

Lighthouse audit showing aria-checked without the value 'true'

Lighthouse uses the states and properties from the WAI-ARIA specification to check that all ARIA attributes have valid values. A page fails this audit when it contains an attributes with an invalid value.

In the example Lighthouse audit above, aria-checked should be set to either true, false, or mixed.

Browsers treat HTML Boolean attributes, such as hidden or checked, as true if they're present in an element's opening tag and false if they're not.

However, ARIA attributes require an explicit true or false value. This is because most ARIA attributes actually support a third stateundefined—or a tristate with an intermediate mixed value.

This issue is important to fix and probably indicates a mistaken assumption in your code. In the example above, the element is still announced as a checkbox, but it will have an implicit state of unchecked, which may not be what's intended.

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

How to fix invalid ARIA attribute values #

Refer to the WAI-ARIA supported states and properties to see the full list of valid ARIA attribute values. Check that you have correct values for any attributes you use.

Also verify that your JavaScript is updating ARIA state values as users interact with your page. 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