React Accessibility: Building Inclusive Components

Neither, inherently. React renders whatever markup you tell it to, so a React app is exactly as accessible as the code you write — it can be flawless or unusable. What React changes is which mistakes are easy to make. Its component model and client-side rendering introduce a specific, repeatable set of traps, and once you know them they are straightforward to avoid.

Three themes cause most React accessibility bugs, and this hub is organized around them:

• Non-semantic markup — reaching for <div> and onClick instead of real elements.
• Lost focus — DOM swapping in and out without managing where focus goes. Covered in depth in focus management in React.
• Silent updates — content changing without a page load and without announcing itself.

JSX looks like HTML but renames a couple of attributes, and those renames are a common source of accessibility bugs — especially forgetting htmlFor, which silently breaks label association.

// Renamed in JSX:
<label htmlFor="email">Email</label>   // not for=
<input id="email" className="field" /> // not class=

// Kept exactly as in HTML — hyphens and all:
<button
  aria-expanded={isOpen}
  aria-controls="menu-list"
  role="button"
>
  Menu
</button>

The key facts: class becomes className and for becomes htmlFor, but aria-*, data-*, and role are written exactly as in HTML — they keep their hyphens and are not camelCased. Event props like onClick are camelCased, but that is a syntax change, not a licence to put click handlers on the wrong element.

Because everything in JSX is "just a component," it is tempting to build every control out of <div> and wire up an onClick. That produces something that looks right and is completely inaccessible: not focusable, not keyboard-operable, and announced as nothing.

// Avoid: not focusable, no keyboard, no role
<div className="btn" onClick={save}>Save</div>

// Prefer: focus, Enter/Space, and "button" role for free
<button type="button" onClick={save}>Save</button>

// Navigation is a link, not an onClick div
<a href="/settings">Settings</a>

A native <button> is focusable, responds to Enter and Space, and is announced as a button — none of which a div gives you without a pile of extra ARIA and key handlers. Reach for the element that matches the job: <button> for actions, <a href> for navigation, <nav>/<main>/<header> for structure. See the semantic HTML guide and the accessible links guide for the full picture. React Fragments (<>...</>) help here too — they let you return multiple elements without wrapping everything in a meaningless <div>.

This is the single biggest React-specific accessibility concern. When React swaps DOM in and out — a route change, a modal opening, a list item removed — the focused element can disappear, and the browser drops focus to the top of the page or nowhere. React does not manage this for you.

The core pattern is a ref plus a useEffect, so focus moves after React commits the DOM:

function Dashboard() {
  const headingRef = useRef(null);

  useEffect(() => {
    headingRef.current?.focus();
  }, []);

  // tabIndex={-1} lets a non-interactive element take programmatic focus
  return <h1 tabIndex={-1} ref={headingRef}>Dashboard</h1>;
}

That is the foundation; the full set of patterns — focus on client-side route changes, trapping focus in modals, and restoring it on close — is covered in the dedicated focus management in React guide, which builds directly on the general focus management guide.

React makes it trivial to change part of the page in response to state — a search result count, a "saved" confirmation, an error. A sighted user sees it; a screen reader user hears nothing, because no page navigation occurred. The fix is an ARIA live region.

function SaveStatus({ message }) {
  // The region must be in the DOM before the text changes,
  // so render it always and update its contents.
  return (
    <p role="status" aria-live="polite">
      {message}
    </p>
  );
}

The critical detail: the live region has to be present in the DOM before its contents change. If you conditionally render the whole element only when a message exists, many screen readers will not announce it, because the region did not exist to be watched. Render the container unconditionally and update the text inside. For urgent messages use role="alert" (assertive); for everything else, aria-live="polite". The live regions guide covers the nuances.

Modals, popovers, and toasts often need to escape a parent with overflow: hidden or a stacking context. React's createPortal renders them elsewhere in the DOM — typically at the end of <body> — while keeping them in the React tree.

import { createPortal } from 'react-dom';

function Modal({ children, onClose }) {
  return createPortal(
    <div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
      {children}
    </div>,
    document.body
  );
}

A portal solves the visual stacking problem, but not the accessibility work: an accessible dialog still needs role="dialog", aria-modal="true", a label, focus moved in on open, focus trapped while open, Escape to close, and focus returned to the trigger on close. Those behaviors are the same as any dialog — follow the modal pattern, and see focus management in React for the focus half.

Three complementary layers catch different classes of problem, and they all wrap the same axe-core engine used across the rest of the ecosystem.

Use all three: the linter for instant feedback, @axe-core/react to surface runtime issues while you develop, and axe in your tests to stop regressions. None of them replaces manual keyboard and screen reader testing — automated tools catch only the deterministic subset. For how these fit the wider picture, see the accessibility testing tools comparison.