axe-core aria-valid-attr-value error invalid value for aria-checked

axe-core aria-valid-attr-value error invalid value for aria-checked - how to fix it

TL;DR

Set aria-checked to a valid value - true, false, or mixed, never yes, no, on, off, or 1 and 0. The same applies to every enumerated aria attribute, check the allowed values and fix the binding. One line of why: assistive tech only understands the spec's token list, anything else is treated as missing.

The error, verbatim

{
  "id": "aria-valid-attr-value",
  "impact": "critical",
  "help": "ARIA attributes must have valid values",
  "nodes": [
{"failureSummary":"Fix any of the following: Invalid ARIA attribute value: aria-checked="maybe"","target":[".toggle"]}
  ]
}

Fix it step by step

Step 1: Reproduce on one page

npx @axe-core/cli https://example.com --rules aria-valid-attr-value --save axe-val.json

Expected: Violations array contains aria-valid-attr-value with the bad value in each failure summary.

Step 2: Extract the bad values

node -e "const r=require('./axe-val.json'); r.violations[0].nodes.forEach(function(n){console.log(n.target.join(' '), '-', n.failureSummary.match(/Invalid ARIA attribute value: ([^\n]+)/)[1])})"

Expected: Lists each attribute with its invalid value.

Step 3: Find the bindings in source

rg -n 'aria-checked' src --glob '*.{jsx,tsx,vue}' | head -20

Expected: Shows the bindings producing the bad values, often a boolean rendered as a string.

Step 4: Correct the values and re-scan

npx @axe-core/cli https://example.com --rules aria-valid-attr-value

Expected: Exit code 0, 0 violations. The toggle now announces checked and unchecked correctly.

Step 5: Gate the rule in CI

npx @axe-core/cli https://example.com --exit | tail -3

Expected: Non-zero exit while any violation remains; add this command to CI so the fix never regresses.

When to use this skill

• Your axe-core report lists this exact rule id under violations
• You are clearing automated WCAG 2.1 AA failures before a release or audit
• A CI a11y gate (pa11y-ci, lighthouse CI, cypress-axe) is red because of this rule

When NOT to use this skill

• The issue only shows up in manual screen-reader testing and axe reports zero violations for the rule
• You are doing a full manual WCAG audit, this skill covers the single automated rule only
• The page is a third-party embed you cannot edit, flag it to the vendor instead

Compatibility

axe-core 4.8+ (rule aria-valid-attr-value, WCAG 4.1.2). Same engine in axe DevTools and pa11y. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

invalid aria attribute value aria-checked

The failureSummary wording, same fix.

axe aria attribute must have valid values

General phrasing covering all enumerated attributes like aria-sort or aria-current.

axe DevTools flags the same rule

The browser extension runs the same rule engine; fix once and it clears in every runner.

Why it happens

Framework bindings love rendering raw values into aria attributes: a JS boolean true becomes the string true (fine), but a custom state like maybe or a 1 and 0 pair does not map to the spec's token list. For aria-checked the only valid values are true, false, and mixed. Axe validates against the ARIA value types (true/false, tristate, token lists, ids), so anything outside the type fails even if it looks sensible to a human. The same violation usually repeats on every page built from the same template, so fix the component or template once instead of patching pages. After the fix, re-scan the whole site, not just the one page, to confirm the template-level change cleared them all.

Edge cases

• In JSX, aria-checked={someBoolean} renders true and false correctly, the bug is usually a string like yes coming from state.
• mixed is only valid on checkbox and menuitemcheckbox, do not use it as a third state elsewhere.
• aria-hidden takes true, false, and the string undefined, the string false is fine, omitting the attribute is not the same.
• Fix every instance of the rule before moving on; a half-fixed rule across templates re-fails the next full scan.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7xuDhsqjuad5ckoukyukBQ