aria-valid-attr-value

Description

An ARIA attribute must use a valid value. This ensures that the value conforms to the expected format and type defined by the WAI-ARIA specification.

When you use an invalid value (e.g., a typo or the wrong data type), assistive technologies cannot correctly interpret the attribute. Assistive technologies like screen readers often ignore the invalid attribute or treat it as having its default value. This prevents users from understanding the component’s correct state, property, or context.

The aria-valid-attr-value rule aligns with WCAG Success Criterion 4.1.2 (Name, Role, Value). This criterion requires that you properly expose the states, properties, and values of user interface components to be programmatically determined.

Examples

In the following incorrect example, the aria-expanded attribute uses the invalid token value "no". This violates the aria-valid-attr-value rule because aria-expanded only accepts the boolean values true or false.

In the following corrected example, the aria-expanded attribute uses the valid boolean value “false”. This ensures that screen readers accurately announce the button’s initial collapsed state.

How to fix?

To fix violations of the aria-valid-attr-value rule, ensure every ARIA attribute you use has a correctly defined value:

• Check the Attribute’s Type: Look up the specific ARIA attribute in the WAI-ARIA specification. Determine its required value type. Common types include:

  • Boolean: true or false (e.g., aria-hidden).

  • Tristate: true, false, or mixed (e.g., aria-checked).

  • Token/Token List: One or more specific string values (e.g., aria-live accepts off, polite, or assertive).

  • Integer/Number: A numerical value (e.g., aria-level, aria-valuenow).

  • ID Reference/ID Reference List: A single or space-separated list of element IDs (e.g., aria-labelledby).

• Verify Spelling: Correctly spell the value according to the specification. Typos like aria-hidden=”flase” will cause a failure.

• Validate References: If the attribute requires an ID reference (e.g., aria-controls, aria-labelledby), ensure the referenced element ID exists on the page and that you spelled the ID correctly.

Reference

• WCAG Success Criterion 4.1.2: Name, Role, Value

• WAI-ARIA States and Properties (Definitions of States and Properties)