eslint jsx-a11y aria-props unknown aria attribute error

eslint jsx-a11y aria-props unknown aria attribute error - how to fix it

TL;DR

Fix the misspelled or made-up aria attribute: the rule checks every aria-* prop against the spec list, so aria-labeledby or aria-described-by fail. Correct the spelling to aria-labelledby or aria-describedby. One line of why: lint is the cheapest place to catch typos that would otherwise ship as silent failures.

The error, verbatim

/app/src/components/Modal.jsx
  22:9  error  Unknown ARIA attribute aria-labeledby. Did you mean aria-labelledby?  jsx-a11y/aria-props

Fix it step by step

Step 1: Reproduce on one file

npx eslint src/components/Modal.jsx --rule '{"jsx-a11y/aria-props": "error"}'

Expected: ESLint prints the aria-props error naming the unknown attribute.

Step 2: Find every unknown aria attribute

npx eslint src | rg 'jsx-a11y/aria-props' | head -20

Expected: Full list of misspelled or invented aria attributes.

Step 3: Correct the spellings

rg -n 'aria-labeledby|aria-described-by|aria-hidden-true' src --glob '*.{jsx,tsx}' | head -20

Expected: Shows common misspellings to fix.

Step 4: Fix and re-lint

npx eslint src | rg -c 'jsx-a11y/aria-props' || echo 0

Expected: Prints 0. The attributes now match the ARIA spec names.

Step 5: Enforce it in CI

npx eslint src --max-warnings 0 | tail -3

Expected: Clean output; add the lint command to CI with max-warnings 0 so the violation cannot come back.

When to use this skill

• Your linter output names this exact jsx-a11y / a11y rule
• You want the violation fixed at author time so it never reaches axe or CI
• You are adding the rule to a shared eslint config and need the fix pattern

When NOT to use this skill

• The failure comes from axe-core or lighthouse at runtime, not from lint
• You plan to disable the rule project-wide, this skill shows the fix, not the escape hatch

Compatibility

eslint-plugin-jsx-a11y 6.7+ with eslint 8 or 9. Catches typos at author time before axe ever sees them. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

unknown aria attribute did you mean

The default message with its helpful suggestion, same fix.

jsx-a11y aria-props typo

Short phrasing, always a spelling fix.

the rule fires in the editor too

With the eslint extension installed, the same error appears inline while typing; the fix is identical.

Why it happens

ARIA attribute names are long and hyphenated, so aria-labelledby becomes aria-labeledby and aria-describedby becomes aria-described-by with depressing regularity. JSX does not validate prop names on DOM elements, so the typo ships silently and the attribute does nothing at runtime. The rule holds the spec's attribute list and flags anything not on it, often with a did-you-mean suggestion. Linter rules catch the violation at author time, which is cheaper than any runtime fix. When this rule fires across many files, fix the shared component and mention it in team onboarding so new code does not reintroduce it.

Edge cases

• The rule only checks the name, not the value, invalid values are the axe aria-valid-attr-value rule's job.
• Custom data- attributes are fine and never flagged, only aria- names are checked.
• Web component authors: your custom aria-* props still need spec names to work with assistive tech.
• After fixing, run the whole lint suite once; a11y rules interact and one fix can surface the next violation.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_a-dLTnYeVsI-UJPdFtH8aQ