axe-core scope-attr-valid error scope on wrong element

axe-core scope-attr-valid error scope on wrong element - how to fix it

TL;DR

Use the scope attribute only on th elements: scope col, row, colgroup, or rowgroup. Move it off td elements and off anything that is not a table header cell. One line of why: scope tells screen readers which cells a header labels, and on a non-header element it is meaningless noise.

The error, verbatim

{
  "id": "scope-attr-valid",
  "impact": "moderate",
  "help": "The scope attribute should be used correctly",
  "nodes": [
    { "target": ["td[scope]"], "failureSummary": "Fix any of the following: Scope attribute should only be used on table header elements" }
  ]
}

Fix it step by step

Step 1: Reproduce on one page

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

Expected: Violations array contains scope-attr-valid with the mis-scoped selectors.

Step 2: List the bad scope usages

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

Expected: Selectors for elements carrying scope that should not.

Step 3: Find them in source

rg -n 'scope=' src --glob '*.{jsx,tsx,vue,html}' | head -20

Expected: Shows every scope attribute to triage.

Step 4: Fix the scope attributes and re-scan

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

Expected: Exit code 0, 0 violations. Screen reader table navigation announces the right headers.

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 scope-attr-valid, WCAG 1.3.1). Pair with td-headers-attr for full table header coverage. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

scope attribute should only be used on table header elements

The failureSummary wording, same fix.

axe scope on td element

The classic copy-paste bug: scope col on a td instead of a th.

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

Table markup gets copied between header and body rows, and the scope attribute rides along onto td elements where it does nothing. Some authors also put scope on div-based grid cells out of habit. Axe validates that scope appears only on th elements with a valid token. The underlying table is usually fine, the attribute is just in the wrong place. 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

• Valid scope tokens are col, row, colgroup, and rowgroup, anything else fails too.
• In simple tables the first row of th elements often needs no scope at all, but explicit scope col never hurts.
• For complex tables with spanned headers, the headers attribute on td is the correct tool, not scope.
• 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_G6eLM54Z9n9YNl5L6tRqTg