ARIA attributes must have valid values.

ARIA attributes each expect a specific type of value. When an attribute receives a value that doesn't match its expected type, browsers and assistive technologies may ignore the attribute entirely or fall back to a default. This can cause screen reader users to miss information about a component's state, purpose, or relationships. For example, setting aria-hidden="yes" instead of aria-hidden="true" means the attribute may be ignored, leaving an element visible to assistive technologies when the developer intended to hide it.

This rule relates to WCAG success criterion 4.1.2 (Name, Role, Value) at Level A. That criterion requires that the name, role, and state of user interface components can be programmatically determined. Invalid ARIA values break this contract because assistive technologies cannot reliably read a state or property whose value doesn't conform to the specification.

Value types in WAI-ARIA

ARIA attributes fall into several value type categories. Each category has its own set of accepted values.

True/false attributes like aria-hidden, aria-disabled, and aria-required accept only "true" or "false". Values like "yes", "no", "1", or "0" are invalid.

Tristate attributes like aria-checked and aria-pressed accept "true", "false", or "mixed". The "mixed" value indicates a partially selected or indeterminate state.

True/false/undefined attributes like aria-expanded accept "true", "false", or "undefined". Setting the value to "undefined" indicates that the expandable/collapsible behavior does not apply.

Token attributes like aria-live, aria-autocomplete, and aria-sort accept a predefined set of keyword values. For instance, aria-live accepts "off", "polite", or "assertive". Any other string is invalid.

ID reference attributes like aria-labelledby and aria-describedby expect one or more IDs pointing to other elements in the DOM. While the referenced elements don't strictly need to exist for the attribute value itself to be "valid" in a syntactic sense, referencing nonexistent IDs means the attribute has no practical effect.

String attributes like aria-label and aria-placeholder accept any non-empty text string.

Number attributes like aria-valuenow, aria-valuemin, and aria-valuemax accept numeric values. Passing a non-numeric string is invalid.

How to fix it

1. Check the WAI-ARIA specification for the attribute you're using to confirm which value type it expects.
2. Make sure boolean attributes use only "true" or "false", not "yes", "no", "1", or "0".
3. For token attributes, use only one of the predefined keyword values listed in the spec.
4. For ID reference attributes, confirm the value contains valid ID strings. If you intend the attribute to point to another element, make sure that element exists in the DOM.
5. For numeric attributes, provide a valid number without extra characters or units.

Some user agents treat ARIA attribute values as case sensitive, so always use lowercase values (e.g., "true" instead of "True").

Examples

Invalid boolean value

The value "yes" is not a valid boolean for aria-hidden. This attribute accepts only "true" or "false".

<p aria-hidden="yes">This text should be hidden from assistive technologies.</p>

Fixed boolean value

<p aria-hidden="true">This text should be hidden from assistive technologies.</p>

Invalid token value

The value "aggressive" is not one of the accepted values for aria-live.

<div aria-live="aggressive">Updates will appear here.</div>

Fixed token value

The correct value is "assertive".

<div aria-live="assertive">Updates will appear here.</div>

Invalid tristate value

The value "partial" is not valid for aria-checked. Tristate attributes accept "true", "false", or "mixed".

<div role="checkbox" aria-checked="partial">Select some items</div>

Fixed tristate value

<div role="checkbox" aria-checked="mixed" tabindex="0">Select some items</div>

Invalid numeric value

The aria-valuenow attribute expects a number, but it receives a string with a unit.

<div role="slider" aria-valuenow="50%" aria-valuemin="0" aria-valuemax="100" aria-label="Volume">
</div>

Fixed numeric value

<div role="slider" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100" aria-label="Volume">
</div>

Invalid boolean value on a required attribute

Using "FALSE" (uppercase) may be treated as invalid by some user agents.

<input type="text" aria-required="FALSE" aria-label="Email">

Fixed with lowercase value

<input type="text" aria-required="false" aria-label="Email">

Learn more:

W3C Reference

Understanding Success Criterion 4.1.2: Name, Role, Value

→

W3C Reference

WAI-ARIA 1.2 Specification: States and Properties

→

MDN Reference

Using ARIA: Roles, states, and properties

→