Fixing Accessibility in React and Next.js

How React apps fail differently from ordinary sites

A traditional website loads a fresh HTML document for each page. The browser resets focus to the top, the screen reader announces the new title, and everything in the markup came from one template. A React application breaks those assumptions in three ways.

• Client-side navigation. Clicking a link swaps part of the page with JavaScript. The browser does not load a new document, so it does not reset focus or announce anything. A screen reader user may hear nothing at all, and focus may stay on a link that no longer exists.
• Components that appear and disappear. When a toast, dropdown or basket row is removed from the tree and it held focus, focus falls back to the <body>. The next Tab press starts again from the top of the page.
• Everything is reusable, including mistakes. A Card or IconButton component written once with a click handler on a <div> puts that fault on every page that uses it.

The general WCAG topics still apply and have their own guides: alt text, form labels, heading structure, colour contrast, focus indicators and ARIA labels. This guide covers what is different when the markup is generated by components.

Tracing a finding back to its component

The Accessibility Audit reports findings against the rendered HTML, which is what browsers and assistive technology receive. In a React app, the job is to map each failing element back to the component that produced it.

1. Group findings by pattern. If the same failure appears on every product card or in every page header, it is one component, not many pages.
2. Use React Developer Tools. Select the failing element in the browser's element inspector, then switch to the Components tab of the React Developer Tools extension, which shows which component rendered it and with which props.
3. Check whether it is yours. If the element comes from a UI library, check the library version and its accessibility notes before patching around it. Many issues are fixed in newer releases or caused by passing the wrong props.
4. Check server-rendered output too. In Next.js, view the page source to see the HTML sent before JavaScript runs. Missing lang attributes, titles and alt text are often visible there.

The fix, step by step

Code you can adapt

A button component that cannot be misused

export function IconButton({ label, icon: Icon, ...props }) {
  return (
    <button type="button" aria-label={label} {...props}>
      <Icon aria-hidden="true" focusable="false" />
    </button>
  );
}

// usage
<IconButton label="Remove from basket" icon={TrashIcon} onClick={remove} />

Making label a required prop (in TypeScript, a non-optional string) means nobody can render an icon button without a name.

A field with connected label, hint and error

import { useId } from 'react';

export function TextField({ label, hint, error, ...props }) {
  const id = useId();
  const hintId = hint ? id + '-hint' : undefined;
  const errorId = error ? id + '-error' : undefined;
  return (
    <div className="field">
      <label htmlFor={id}>{label}</label>
      {hint && <p id={hintId}>{hint}</p>}
      <input
        id={id}
        aria-describedby={[hintId, errorId].filter(Boolean).join(' ') || undefined}
        aria-invalid={error ? true : undefined}
        {...props}
      />
      {error && <p id={errorId}>{error}</p>}
    </div>
  );
}

Focusing the page heading after navigation (Next.js App Router)

'use client';
import { usePathname } from 'next/navigation';
import { useEffect, useRef } from 'react';

export function PageHeading({ children }) {
  const ref = useRef(null);
  const pathname = usePathname();
  const first = useRef(true);
  useEffect(() => {
    if (first.current) { first.current = false; return; }
    ref.current?.focus();
  }, [pathname]);
  return <h1 ref={ref} tabIndex={-1}>{children}</h1>;
}

Use this component for the main heading in each page. In React Router the same idea works with the useLocation hook. Give the heading a focus style that is visible but not jarring, since it is not an interactive element.

A live region that is always present

export function StatusMessage({ message }) {
  return (
    <div role="status" aria-live="polite" className="status">
      {message}
    </div>
  );
}

Render StatusMessage once near the top of the layout and change its message prop. Screen readers announce changes to a region they are already watching; a region that is mounted at the same moment as its text is often missed.

Next.js specifics

The route announcer tells screen reader users that a new page loaded, but it does not move keyboard focus. Test whether your layout keeps focus somewhere sensible after navigation; if focus is left on a link in a menu that has now closed, add the heading focus pattern above.

Choosing component libraries

A good headless or styled component library can save weeks of work, because it ships widgets that already follow the W3C ARIA Authoring Practices keyboard patterns. Libraries widely used for this include React Aria from Adobe, Radix UI, Headless UI and Ariakit; styled systems such as MUI build on similar patterns. When comparing them, look for:

• Documentation that states the keyboard interactions for each component.
• Focus trapping and focus return built into dialogs and popovers.
• Props for accessible names, and warnings in development when they are missing.
• Active maintenance and a public issue tracker where accessibility bugs are fixed.

Testing strategy that fits a component codebase

1. While coding: the ESLint jsx-a11y rules and a browser extension based on axe-core highlight problems in the page you are working on. The older @axe-core/react console helper does not support React 18 and later, so do not rely on it for current apps.
2. In unit and component tests: query by role and accessible name with Testing Library, and assert no axe violations on rendered components with jest-axe or an equivalent for Vitest.
3. In end-to-end tests: run axe on key pages and after key interactions, for example with @axe-core/playwright, and script keyboard journeys such as opening the menu and completing checkout with key presses only.
4. Before release: run the Accessibility Checker on each page type, and do a short manual pass with a keyboard and with NVDA or VoiceOver.

import { render, screen } from '@testing-library/react';
import { axe } from 'jest-axe';
import { ProductCard } from './ProductCard';

test('product card is accessible', async () => {
  const { container } = render(<ProductCard name="Oak side table" price="£120" />);
  expect(screen.getByRole('link', { name: 'Oak side table' })).toBeInTheDocument();
  expect(screen.getByRole('button', { name: /add oak side table to basket/i })).toBeInTheDocument();
  expect(await axe(container)).toHaveNoViolations();
});

This test needs the toHaveNoViolations matcher from jest-axe and the DOM matchers from @testing-library/jest-dom registered in your test setup file.

Edge cases

Portals and stacking

Modals rendered with createPortal sit at the end of the body in the DOM, far from the button that opened them. Without focus management, keyboard users must Tab through the whole page to reach them. Move focus in on open, contain it, and return it on close, or use <dialog> with showModal(), which handles the containment for you.

The inert attribute

To stop focus reaching the page behind an open drawer, add inert to the main content wrapper. React 19 accepts it as a normal boolean prop; earlier versions need it passed as an empty string when true and left off when false.

Fragments and invalid structure

Components that return a wrapping <div> inside a <ul> or <table> break list and table semantics, so screen readers stop announcing item counts or column headers. Return a fragment, or make the component render the <li> or <tr> itself.

Animations

Respect the reduced motion setting with the prefers-reduced-motion media query, and check that animation libraries you use do the same for page transitions and parallax effects.