EAA compliance for Gatsby: WCAG 2.1 AA checklist & fixes

What the EAA actually requires from a Gatsby site

Gatsby generates static HTML at build time, so under the EAA it has a head start and the obligation narrows to its React-driven client navigation and image discipline. EN 301 549 conformance forces you to add focus management to @reach/router-based gatsby-link navigation, which does not move focus to main, and to enforce the alt prop on GatsbyImage, which is TypeScript-optional and defaults to undefined so screen readers announce the file name. The built static output is otherwise accessible, so the requirement is essentially route-focus handling and alt-text enforcement.

Gatsby is common for marketing and documentation sites, so in-scope Gatsby sites are usually content or brochure surfaces for businesses of varying size, with fine exposure tracking the operator. A small business faces fixed national penalties, while a larger company's Gatsby marketing or commerce site could reach turnover-percentage territory. A practical, forward-looking consideration is that Gatsby's ecosystem momentum has slowed relative to Astro and Next.js, so for existing sites the pragmatic path is to fix the two unique risks rather than migrate for accessibility reasons alone.

Remediation is a developer change in the codebase: a layout wrapper that focuses main on every @reach/router location change, and making the GatsbyImage alt prop required through linter configuration and code review. Add gatsby-plugin-react-axe in development and run scans against the built static output rather than the dev server. Because the framework-specific surface is small, a single developer can close these gaps in a short, well-scoped effort.

Top WCAG failures we see on Gatsby sites

Across hundreds of Gatsby scans, the same handful of issues show up over and over. None of them require ripping the theme apart — most are fixable in a few hours by someone comfortable in the platform's editor or template files.

• Client-side navigation without focus management

  gatsby-link does not move focus to <main>.

  2.4.3

• GatsbyImage alt prop omitted

  TypeScript-optional alt allows shipping images without descriptions.

  1.1.1

Concrete code fixes for Gatsby

Below are copy-paste fixes for the most common Gatsby issues. They assume you have access to your theme code or the platform's custom-code injection panel. If you cannot edit code directly, share these snippets with whoever maintains the site — every one of them is a ten-minute change.

import { useEffect } from 'react';
import { useLocation } from '@reach/router';

export function FocusOnNav() {
  const location = useLocation();
  useEffect(() => {
    const main = document.querySelector('main');
    if (main instanceof HTMLElement) {
      main.setAttribute('tabindex', '-1');
      main.focus();
    }
  }, [location.pathname]);
  return null;
}

Tools and plugins worth installing first

• gatsby-plugin-react-axe in development

How to scan a Gatsby site without missing anything

Automated scanners catch about 30–40% of WCAG issues; the rest need manual review. The good news is that the 30–40% includes the most expensive issues to remediate after the fact, so an automated scan is the cheapest way to get unstuck. Run one before you change a line of theme code.

• Run on the built static output, not the dev server.