eslint jsx-a11y no-autofocus error breaks screen reader focus

eslint jsx-a11y no-autofocus error breaks screen reader focus - how to fix it

TL;DR

Remove autoFocus props and autofocus attributes, and move focus deliberately in an effect after mount instead. Autofocus on page load yanks screen reader users to the middle of the page with no context. One line of why: focus is a user's place in the page, and stealing it on load is disorienting for everyone, worst for screen reader users.

The error, verbatim

/app/src/components/Search.jsx
  14:9  error  The autoFocus prop is not recommended  jsx-a11y/no-autofocus

Fix it step by step

Step 1: Reproduce on one file

npx eslint src/components/Search.jsx --rule '{"jsx-a11y/no-autofocus": "error"}'

Expected: ESLint prints the no-autofocus error.

Step 2: Find every autofocus

npx eslint src | rg 'jsx-a11y/no-autofocus' | head -20

Expected: Full list of autoFocus usages.

Step 3: Replace with deliberate focus management

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

Expected: Shows each usage; modal opens and error summaries may keep programmatic focus via effect, page-load autofocus goes.

Step 4: Fix and re-lint

npx eslint src | rg -c 'jsx-a11y/no-autofocus' || echo 0

Expected: Prints 0. Focus now moves only in response to user actions.

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. The rule flags the autoFocus prop and the autofocus attribute. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

the autofocus prop is not recommended

The default message, same fix.

jsx-a11y autofocus search input

The classic: autofocus on a search box that hijacks every page load.

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

Autofocus feels helpful (put the cursor in the search box) but on page load it moves focus before the screen reader has announced the page, so the user loses all context. The rule bans the declarative prop outright. The legitimate cases (moving focus into an opened modal, to an error summary after submit) are programmatic and intentional, done in effects in response to user actions, not declarative autofocus. 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

• Moving focus into a modal on open is correct and expected, do it in an effect, not with autoFocus.
• After form submit with errors, moving focus to the error summary is the recommended pattern.
• On route change in SPAs, move focus to the new h1, that is deliberate focus management, not autofocus.
• 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_OLd3J5HbkpHnTMTIw3IKyQ