React Accessibility Checklist

A React-specific accessibility checklist covering the patterns that break in JSX: focus management on route changes, ARIA state syncing with React state, useId for accessible IDs, Portals + dialogs, controlled-component form accessibility, and React Testing Library practices. Pair it with the Developer checklist for non-React-specific items.

Interactive React

0 of 36 items complete

Component Architecture

JSX uses semantic HTML, not styled <div>s Render <button>, <nav>, <main>, <article> — not <div onClick>. The native elements give you focus, keyboard handlers, role announcement, and form behavior for free. (SC 4.1.2) Semantic HTML guide
useId() generates stable accessible IDs Use React's useId hook for any ID that aria-labelledby, aria-describedby, or <label htmlFor> references. Hard-coded IDs collide when a component renders twice; Math.random() breaks hydration.
forwardRef exposes the underlying DOM node Custom components that wrap form inputs or interactive elements should forward their ref so parent components can move focus to them. Without forwardRef, you can't focus() them programmatically.
useEffect cleanups remove all event listeners Any addEventListener in a useEffect must be paired with a removeEventListener in the return cleanup. Orphaned listeners cause memory leaks and unexpected ARIA state on unmount.
onSubmit calls e.preventDefault() only when handling submit in JS If your form has a real backend endpoint, let the native form behavior work — don't prevent default. Native forms work without JS (progressive enhancement). Override only when fully handling submit client-side.
Render-prop / HOC wrappers don't strip ARIA attributes If you wrap an input in a styled component or HOC, spread ...rest through so aria-*, data-*, and event handlers reach the underlying element.

Focus Management

Focus moves on route change (React Router / Next.js) After navigation, move focus to the new page's <h1> (with tabindex="-1" + .focus()) or to a hidden announcement region. Without this, screen reader users stay focused on the old page. Focus Management guide
document.title updates on route change Use useEffect + document.title = '...', or a router helper like react-helmet / Next.js metadata API. Screen readers announce the title on load and on title change.
Modals trap focus while open and return it on close Use the native <dialog> element with showModal() — it handles focus trap, escape key, and return-on-close natively. If you can't use <dialog>, the focus-trap-react library handles it. Modal pattern
React Portals manage focus across DOM boundaries createPortal renders elsewhere in the DOM but React's synthetic event system follows the React tree. Focus traps must explicitly find the portal's DOM root; document.activeElement behaves normally but tab order follows DOM order, not React's tree.
autoFocus is reserved for modal/dialog mount only autoFocus on page load yanks focus away from where the user was. Use it only inside modals, popovers, or step-based wizards where focus-on-mount is expected.
Disabled buttons don't trap keyboard focus traversal Native disabled removes the button from tab order — usually fine. If you need the button discoverable but inactive, use aria-disabled="true" + ignore click/keydown handlers. Don't use tabindex="-1" for disabling. Button pattern

ARIA + State

aria-expanded reflects React state, not initial render aria-expanded={isOpen} — JSX expression, not a static string. Same for aria-pressed, aria-selected, aria-current, aria-checked. Screen readers announce state changes in real time. ARIA guide
aria-live regions are mounted before content is announced The region must exist in the DOM before the message text changes. Don't conditionally render the entire aria-live container — render it empty, then update its text. Live Regions guide
aria-busy="true" during async loading Set aria-busy on a container while async content loads, then remove it when done. Screen readers know to wait for stable content before reading.
Avoid role attribute overrides on semantic elements <button role="button"> is redundant. <nav role="navigation"> is redundant. Let native semantics work. First rule of ARIA: don't use ARIA.
Custom widgets follow WAI-ARIA Authoring Practices Tabs, comboboxes, menus, listboxes have established keyboard + ARIA patterns. Use a library (e.g., Headless UI, Radix UI, React Aria) or follow the WAI-ARIA spec — don't reinvent. Pattern library
aria-label on buttons doesn't override visible text confusingly Speech-control users say what they see. If a button shows "Submit," don't aria-label="Send" — either match visible text or contain it. (SC 2.5.3)

Forms

Every <input> has a <label htmlFor> Pair via useId so IDs match. Don't substitute placeholder for a label — placeholders disappear on focus. Form Labeling guide
Controlled vs uncontrolled chosen deliberately Controlled inputs (value + onChange) work well for live validation. Uncontrolled inputs (with refs) work well for one-shot submission. Mixing them mid-component breaks form state.
Validation errors announce via aria-describedby + aria-invalid Wire each error message's ID into the input's aria-describedby. Set aria-invalid="true" on the field. Screen readers narrate the error when the field is focused. Forms pattern
Submit failures move focus or announce via role="alert" After failed submit, either move focus to the first error field or to a summary region with role="alert" at the top. Don't fail silently.
autocomplete attributes on identifying inputs autocomplete="name", autocomplete="email", etc. Password managers and accessibility tools rely on these. (SC 1.3.5)
Disabled submit button has aria-disabled fallback for context <button disabled> removes from tab order. If users need to discover why a button can't be activated, use aria-disabled="true" + custom handler that does nothing, so the button stays focusable and announces "unavailable."

Performance & Rendering

Strict Mode catches effect double-runs Wrap your app in <StrictMode> in development. Effects run twice, exposing missing cleanups (which often manifest as orphaned focus/aria state in production).
Suspense boundaries don't strand screen readers mid-announcement When a Suspense boundary swaps from loader to content, ensure focus doesn't jump or get lost. Wrap loaders in an aria-live="polite" region so the change announces.
Lazy-loaded components have a focus + announce strategy Code-split routes mount fresh — move focus to the new view's heading like a normal route change. Suspense fallbacks should announce "Loading…" via role="status".
Hydration mismatches don't strip ARIA attributes If your SSR + client render disagree, React re-renders entirely on the client. Test SSR + hydration with a screen reader watching — any ARIA attribute that only appears client-side will not announce on first paint.
React.memo / useMemo don't skip ARIA prop updates If a memoized component receives aria-expanded={isOpen} as a prop, ensure your dependency array includes the state. Stale ARIA props cause screen readers to announce wrong state.
Animations use prefers-reduced-motion, including JS-driven ones useReducedMotion from Framer Motion / Spring or a custom matchMedia hook. Don't trigger entry/exit animations for users who've opted out. (SC 2.3.3)

Testing

React Testing Library queries prefer getByRole Querying by role (getByRole('button', { name: /save/i })) matches what screen readers see. Avoid getByTestId for anything a user actually interacts with — test IDs are invisible to assistive tech.
Keyboard interactions tested with userEvent Use @testing-library/user-event (v14+) for Tab, Enter, Escape, arrow keys. Avoid fireEvent.click for keyboard-only flows — it bypasses focus, which is half the bug surface.
Focus assertions verify focus moves correctly After every focus-changing action (modal open, route change, error), assert expect(targetEl).toHaveFocus(). This catches the entire class of "focus lost" bugs.
ARIA state assertions check expanded/selected/checked across renders expect(button).toHaveAttribute('aria-expanded', 'true'). Run after every state-changing interaction. Catches the regression where state updates but ARIA doesn't.
Snapshot tests don't mask ARIA regressions Plain snapshot tests pass if the markup is "the same." Use toHaveAccessibleName / toHaveAccessibleDescription from @testing-library/jest-dom to assert the *computed* accessibility name.
Run jest-axe on critical-flow renders const results = await axe(container); expect(results).toHaveNoViolations(). Catches missing labels, broken ARIA references, contrast issues that escape unit tests. Run in CI.

Frequently asked questions

Why a React-specific checklist? Doesn't WCAG apply equally?

WCAG is framework-agnostic, but the implementation pitfalls in React are framework-specific. SPAs break browser-default focus management on route change; React's render model can strip ARIA attributes during hydration; Portals decouple React tree from DOM tree. These patterns don't exist in vanilla HTML, so they're not in the standard developer checklist.

Does this replace the developer checklist?

No — pair them. The Developer checklist covers WCAG 2.2 AA across all 4 POUR principles (semantic HTML, contrast, keyboard, ARIA, forms, etc). This React checklist covers the specific React integration patterns that surface bugs in those areas. Run both.

Does this work for Next.js, Remix, Gatsby?

Yes — the items apply to any React-based framework. Route-change focus uses the framework's router hook (Next.js useRouter, Remix useNavigation, etc.) instead of React Router, but the underlying behavior is the same. SSR-specific items (hydration, Suspense) apply to Next.js and Remix more than Gatsby's static-export model.

What about React Server Components?

RSCs render on the server, so they hit the same hydration concerns as classic SSR — ARIA attributes from server render must match client. The interactive items (focus management, ARIA state, form handling) all apply to client components inside an RSC tree, no different than in a fully-client React app.

Should I use a UI library like Radix, Headless UI, or React Aria?

Strongly recommended for complex widgets (combobox, menu, dialog, tabs, listbox). These libraries handle the WAI-ARIA Authoring Practices patterns correctly — keyboard navigation, focus traps, ARIA state — which is hours of work per component to get right yourself. Radix and React Aria are the most thorough.

How do I test all this? Manual or automated?

Both. Automated: jest-axe in unit tests, @testing-library/user-event for keyboard flows, focus + ARIA assertions in component tests. Manual: walk every primary flow with a real screen reader (NVDA + Firefox, or VoiceOver + Safari). Automated catches ~30% of issues; manual catches the rest. See the Testing checklist for the full testing flow.

What about Vue, Svelte, or Solid?

The same architectural concerns apply — SPA route changes, dynamic ARIA state, form accessibility — but the framework APIs differ. Per-framework checklists are on the roadmap. Until then, this checklist's concepts (not the React-specific code) transfer cleanly to other frameworks.

Is React 18+ better for accessibility than older versions?

Yes, modestly. useId (React 18) replaces the older error-prone manual ID generation. Concurrent rendering's useTransition makes it easier to manage loading states without stranding focus. Suspense boundaries are more usable. But the bulk of accessibility work remains the same as React 16 — focus management, ARIA, semantic HTML.