Gatsby Accessibility Checklist 2026 | WCAG 2.1 AA & EAA Compliance

Gatsby is a React-based static site generator that produces fast, pre-rendered websites from various data sources including Markdown, CMSes, and APIs. While Gatsby's server-side rendering and static HTML output provide a solid foundation for accessibility, the client-side hydration and React-based routing introduce significant accessibility challenges that developers must address deliberately. Gatsby's reliance on client-side navigation means that page transitions do not trigger the browser's native page-load announcements, leaving screen reader users unaware that new content has loaded. Additionally, Gatsby's rich plugin ecosystem means that third-party components may introduce accessibility barriers that are not immediately obvious. The gatsby-plugin-image component, while excellent for performance, requires careful configuration to ensure alt text is always provided and meaningful. As the European Accessibility Act enforcement ramps up across EU member states, Gatsby site owners must pay attention to focus management during route changes, semantic HTML in React components, keyboard operability of interactive elements, and proper ARIA usage throughout their component tree. This checklist covers the most common accessibility issues found in Gatsby sites and provides concrete fixes that work within Gatsby's React and GraphQL architecture.

Common Accessibility Issues

// gatsby-browser.js
// No route change handling - screen readers get no feedback
export const onRouteUpdate = ({ location }) => {
  // only analytics tracking
  trackPageView(location.pathname)
}

// gatsby-browser.js
export const onRouteUpdate = ({ location }) => {
  const pageTitleElement = document.querySelector('h1')
  const pageTitle = pageTitleElement
    ? pageTitleElement.textContent
    : document.title
  
  // Announce route change to screen readers
  const announcer = document.getElementById('route-announcer')
  if (announcer) {
    announcer.textContent = `Navigated to ${pageTitle}`
  }
  
  // Move focus to main content
  const mainContent = document.querySelector('main')
  if (mainContent) {
    mainContent.setAttribute('tabindex', '-1')
    mainContent.focus()
  }
}

<StaticImage
  src="../images/team-photo.jpg"
  layout="constrained"
  width={800}
/>

<GatsbyImage
  image={data.heroImage.childImageSharp.gatsbyImageData}
/>

<StaticImage
  src="../images/team-photo.jpg"
  alt="Our accessibility team reviewing test results in the office"
  layout="constrained"
  width={800}
/>

<GatsbyImage
  image={data.heroImage.childImageSharp.gatsbyImageData}
  alt={data.heroImage.altText}
/>

<div className="layout">
  <div className="header">
    <div className="nav">...</div>
  </div>
  <div className="content">
    <div className="title">Page Title</div>
    <div className="body">Content here</div>
  </div>
  <div className="footer">...</div>
</div>

<div className="layout">
  <header>
    <nav aria-label="Primary navigation">...</nav>
  </header>
  <main id="main-content">
    <h1>Page Title</h1>
    <div className="body">Content here</div>
  </main>
  <footer>...</footer>
</div>

// Using a plugin that renders an inaccessible modal
import { PluginModal } from 'gatsby-plugin-fancy-modal'

<PluginModal trigger={<span>Open</span>}>
  <div>Modal content with no focus management</div>
</PluginModal>

// Custom accessible modal component
import { Dialog } from '@reach/dialog'
import '@reach/dialog/styles.css'

<button onClick={() => setShowModal(true)}>
  Open details
</button>
<Dialog
  isOpen={showModal}
  onDismiss={() => setShowModal(false)}
  aria-label="Feature details">
  <p>Modal content with proper focus trapping</p>
  <button onClick={() => setShowModal(false)}>Close</button>
</Dialog>

const loadMore = async () => {
  const newItems = await fetchMoreItems()
  setItems([...items, ...newItems])
  // Focus stays wherever it was or gets lost
}

const resultsRef = useRef(null)

const loadMore = async () => {
  const newItems = await fetchMoreItems()
  setItems([...items, ...newItems])
}

useEffect(() => {
  if (resultsRef.current) {
    resultsRef.current.setAttribute('tabindex', '-1')
    resultsRef.current.focus()
  }
}, [items])

<h2 ref={resultsRef}>Showing {items.length} results</h2>

Gatsby-Specific Tips

• Use gatsby-plugin-accessible-routing or a custom RouteAnnouncer in gatsby-browser.js to ensure screen readers announce page changes during client-side navigation. Test with NVDA or VoiceOver to verify announcements occur on every route change.
• Configure the jsx-a11y ESLint plugin in your Gatsby project's .eslintrc to catch accessibility issues during development. Gatsby's default ESLint config does not include accessibility rules, so you must add eslint-plugin-jsx-a11y explicitly.
• When using gatsby-plugin-image, always source alt text from your CMS or Markdown frontmatter through GraphQL queries rather than hardcoding it. This ensures content editors can update alt text without code changes.
• Test your Gatsby site both with JavaScript enabled (hydrated React) and with JavaScript disabled (static HTML) to ensure that the server-rendered output is accessible on its own, as some users and search engines will see the non-hydrated version.

Recommended Tools

Further Reading

• Alt Text Guide
• Keyboard Navigation Testing
• Five Minute Accessibility Audit

Other CMS Checklists

• Nextjs Accessibility Checklist
• Hugo Accessibility Checklist