eslint jsx-a11y media-has-caption error missing captions

eslint jsx-a11y media-has-caption error missing captions - how to fix it

TL;DR

Add a track element with kind captions to every audio and video element, pointing at a real captions file. Muted decorative video can be exempted, but content video needs captions. One line of why: lint catches the missing track before the video ships to users who depend on captions.

The error, verbatim

/app/src/components/Player.jsx
  7:5  error  Media elements such as audio and video must have a track for captions  jsx-a11y/media-has-caption

Fix it step by step

Step 1: Reproduce on one file

npx eslint src/components/Player.jsx --rule '{"jsx-a11y/media-has-caption": "error"}'

Expected: ESLint prints the media-has-caption error.

Step 2: Find every media element

npx eslint src | rg 'media-has-caption' | head -20

Expected: Full list of audio and video elements missing caption tracks.

Step 3: Audit which media needs captions

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

Expected: Shows media usages; content media needs tracks, muted loops may be decorative.

Step 4: Add tracks and re-lint

npx eslint src | rg -c 'media-has-caption' || echo 0

Expected: Prints 0. The player now offers captions from a real captions file.

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 checks audio, video, and track elements. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

media elements must have a track for captions

The default message, same fix.

jsx-a11y video missing captions track

The usual instance: marketing video embeds without a track element.

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

Video players get built with a src and controls but no track element because captions files are produced later by another team or not at all. The rule requires a track child on audio and video elements. It cannot verify the captions file exists or is correct, only that the track element is present, so this is a presence check, not a quality check. 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

• Muted, decorative, autoplaying loops can legitimately skip captions, but document the exemption.
• A track element with kind subtitles is not the same as captions, use kind captions for the deaf and hard-of-hearing audience.
• The rule does not check the src of the track, an empty or 404 captions file passes lint but fails users.
• 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_Phg1QAtRGQ1G7ZPOr9PsPA