eslint jsx-a11y click-events-have-key-events error

eslint jsx-a11y click-events-have-key-events error - how to fix it

TL;DR

Pair every onClick on a non-interactive element with a keyboard handler (onKeyDown or onKeyUp), or better, replace the div with a real button. The rule wants keyboard parity for mouse handlers. One line of why: mouse-only controls lock out keyboard users entirely, and a key handler is the minimum parity.

The error, verbatim

/app/src/components/Card.jsx
  15:5  error  Visible, non-hidden elements with click handlers must have at least one keyboard listener  jsx-a11y/click-events-have-key-events

Fix it step by step

Step 1: Reproduce on one file

npx eslint src/components/Card.jsx --rule '{"jsx-a11y/click-events-have-key-events": "error"}'

Expected: ESLint prints the click-events-have-key-events error.

Step 2: Find every mouse-only handler

npx eslint src | rg 'click-events-have-key-events' | head -20

Expected: Full list of elements with onClick but no keyboard handler.

Step 3: Prefer real buttons

rg -n 'onClick' src/components/Card.jsx | head -10

Expected: Shows the handlers; for each, decide: real button element (best) or add onKeyDown plus tabIndex and role (fallback).

Step 4: Fix and re-lint

npx eslint src | rg -c 'click-events-have-key-events' || echo 0

Expected: Prints 0. Keyboard test: every control now activates with Enter or Space.

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. Pair with jsx-a11y/no-static-element-interactions, which usually fires alongside. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

visible non-hidden elements with click handlers must have keyboard listener

The default message, same fix.

jsx-a11y onClick div needs key handler

Practitioner phrasing for the classic clickable-div pattern.

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

Clickable divs and spans are everywhere in React code because onClick works on any element. The rule requires a keyboard listener alongside click handlers on visible non-interactive elements. Adding onKeyDown alone is not enough for a good experience (you also need tabIndex and a role, which the sibling rules enforce), which is why the real fix is usually swapping to a button element. 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

• Hidden elements (aria-hidden or display none) are exempt, the rule only checks visible elements.
• onClick on a real button or link never triggers this rule, only non-interactive elements.
• Adding an empty onKeyDown handler silences the rule but helps nobody, implement real key handling or use a button.
• 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_FUfJBaPLAxP-Avpug8uDQQ