axe-core aria-hidden-focus focusable content inside aria-hidden bug

axe-core aria-hidden-focus focusable content inside aria-hidden bug - how to fix it

TL;DR

Remove focus from anything inside an aria-hidden container: either un-hide the container or make its children unfocusable (tabindex -1, disabled, or inert). Do both and the violation clears. One line of why: aria-hidden tells screen readers the content does not exist, but keyboard focus can still land on it, leaving sighted keyboard users and screen reader users in two different places.

The error, verbatim

{
  "id": "aria-hidden-focus",
  "impact": "serious",
  "help": "ARIA hidden element must not contain focusable elements",
  "nodes": [
    { "target": [".modal-backdrop[aria-hidden]"], "failureSummary": "Fix any of the following: Focusable content should be disabled or be removed from the DOM" }
  ]
}

Fix it step by step

Step 1: Reproduce on one page

npx @axe-core/cli https://example.com --rules aria-hidden-focus --save axe-hidden.json

Expected: Violations array contains aria-hidden-focus with the hidden container selectors.

Step 2: Identify the focusable descendants

node -e "const r=require('./axe-hidden.json'); r.violations[0].nodes.forEach(function(n){console.log(n.target.join(' '))})"

Expected: Selectors for the focusable elements trapped inside aria-hidden subtrees.

Step 3: Decide hide vs un-hide per container

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

Expected: Shows each aria-hidden usage so you can decide: background content behind a modal stays hidden and gets inert, visible content loses the aria-hidden.

Step 4: Apply the fix and re-scan

npx @axe-core/cli https://example.com --rules aria-hidden-focus

Expected: Exit code 0, 0 violations. Keyboard test: tabbing never lands on invisible content.

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-hidden-focus, WCAG 4.1.2). Common with modal and drawer implementations in React, Vue, and Angular. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

focusable content should be disabled or removed from the dom

The failureSummary wording, same fix.

aria-hidden true contains focusable element

Practitioner phrasing, usually a modal backdrop or collapsed drawer.

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

Modal and drawer components set aria-hidden true on background content (correct) but leave links and buttons inside it focusable (wrong). CSS visibility and display do remove focusability, but aria-hidden alone does not, it only hides from the accessibility tree. The mismatch means a keyboard user tabs into content the screen reader insists does not exist. The native inert attribute fixes both trees at once, which is why it is the recommended fix. 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

• The inert attribute is the clean fix for background content, it removes focus and pointer events together.
• Do not slap tabindex -1 on every child by hand, you will forget the dynamically added ones, inert the container.
• aria-hidden on a focused element itself is fine, the rule only cares about focusable descendants.
• 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_2-9n6wDlwXbcdmNDfLlm7g