ARIA Attributes Must Conform to Valid Values: How to Fix It

What this check flags

This rule fires when an ARIA attribute is spelled correctly but its value is wrong for the type that attribute accepts — a boolean set to "yes", an ID reference pointing at an element that doesn’t exist, a token like aria-current="page-two" that isn’t in the allowed list, or a number outside its range. This is the value being invalid, not the attribute name. A bad value is often worse than a missing one: assistive tech may ignore the whole attribute, so a control silently loses its checked, expanded, or current state without any visible clue.

Here’s the part that makes this failure sneaky: it fails silently and it fails invisibly. There’s no red console error, nothing looks broken on screen, and the attribute is right there in the DOM inspector looking perfectly reasonable. But the browser’s ARIA parser reads aria-expanded="expanded", decides that isn’t a valid boolean, and throws the whole attribute away. Now your disclosure widget never announces whether it’s open or closed, and you won’t notice unless you’re actually driving the page with a screen reader. The gap between “looks fine” and “is fine” is exactly what this check exists to close.

A real failing snippet, and the fix

Here’s a nav item and a toggle that each carry a mistyped value:

<!-- FAILS: "true" isn't a valid aria-current token;
     "expanded" isn't a valid boolean -->
<a href="/pricing" aria-current="true">Pricing</a>
<button aria-expanded="expanded">Menu</button>

The attribute names are perfectly valid — the values aren’t. aria-current takes a specific token set (page, step, true…), and while true is legal for it, on a current nav item you want page. aria-expanded is a strict boolean, so it must be true or false:

<!-- PASSES: values match each attribute's value type -->
<a href="/pricing" aria-current="page">Pricing</a>
<button aria-expanded="false">Menu</button>

The gotcha that catches people: ARIA booleans are the strings "true"/"false", not the HTML style where the attribute’s mere presence means true. Writing aria-expanded with no value, or with "1", or with an empty string, is invalid.

ARIA value types and what they accept

Every ARIA attribute has a declared value type. Match the value to the type and this check passes.

How to detect it

1. axe DevTools: the “ARIA attributes must conform to valid values” violation names each attribute and shows the invalid value it found alongside the value type it expected.
2. Lighthouse: run the Accessibility audit; this appears in the ARIA group with each non-conforming attribute listed on its element.
3. ARIA DevTools / accessibility tree: inspect the element and compare its computed states against the DOM. If a state you set isn’t reflected in the tree, the value was rejected as invalid.

How to fix it

1. Read the violation to see the offending attribute and the value type it expects.
2. For booleans and tristates, use the exact string true/false/mixed — not 1, yes, or a bare attribute.
3. For token attributes, pick a value from that attribute’s allowed list.
4. For ID-reference attributes, confirm the target id actually exists and is unique on the page.
5. For numeric attributes, keep the value within the valid range (e.g. aria-valuenow between min and max).
6. Re-scan and verify the state now appears correctly in the accessibility tree.

The most reliable way to stop these at the source is to stop generating the strings by hand. When a framework binds aria-expanded={isOpen} to a real boolean, you can’t accidentally ship "expanded" — the value is always true or false. The failures cluster around string interpolation and templating, where aria-checked="{{status}}" happily emits whatever status holds, valid token or not. If you keep tripping this check, audit the templates that build these attributes rather than the individual elements; the bug is usually upstream in one helper, not scattered across fifty components.

If the problem turns out to be a misspelled attribute name rather than a bad value — aria-lable, aria-role — that’s a different failure covered by elements must only use allowed ARIA attributes.

FAQ

What’s the difference between an invalid value and an invalid attribute?

An invalid value means the attribute exists but you gave it something it can’t accept (aria-checked="checked"). An invalid attribute means the name itself is wrong or misspelled. This check is only about values — the name half lives in allowed ARIA attributes.

Why is a bad value worse than leaving the attribute off?

When a value is invalid, assistive tech often discards the entire attribute, so the control loses that state entirely and with no warning. A toggle that should announce “pressed” simply won’t.

Can I use HTML-style boolean attributes with ARIA?

No. In HTML, disabled is true just by being present. ARIA booleans must carry the explicit string value "true" or "false" — presence alone is invalid.

Is aria-current="true" wrong?

Not strictly — true is one of the accepted tokens for aria-current. But on a navigation link marking the current page, page is more precise and announces better. Reserve true for cases with no more specific token. Related roles’ value rules interact with the containment checks too.