Accessibility in React

React renders to the DOM, so the accessibility of a React application is the accessibility of the HTML it produces. The framework neither grants it nor prevents it. What it does is make it easy to build a control out of the wrong elements, because a div is as convenient to render as a button.

Two things carry most of the weight. The elements you choose, because browsers already implement keyboard behaviour, focus and announcement for the standard ones. And focus, because focus is how a keyboard user knows where they are and a screen reader user knows what is being read.

This lesson is deliberately last in the course, not because accessibility comes last, but because it needs the state, effect and composition ideas that came before. Earlier lessons already used labelled inputs and real buttons rather than saving them for here.

"use client";

import { useEffect, useRef } from "react";

type Employee = { id: string; name: string; jobTitle: string; department: string };

export function EmployeeDetailDialog({
  employee,
  onClose,
}: {
  employee: Employee;
  onClose: () => void;
}) {
  const closeButtonRef = useRef<HTMLButtonElement>(null);
  const openerRef = useRef<Element | null>(null);

  useEffect(() => {
    // Remember what had focus, then move focus into the dialog.
    openerRef.current = document.activeElement;
    closeButtonRef.current?.focus();

    function handleKeyDown(event: KeyboardEvent) {
      if (event.key === "Escape") onClose();
    }

    document.addEventListener("keydown", handleKeyDown);

    return () => {
      document.removeEventListener("keydown", handleKeyDown);
      // Put focus back where the user left it.
      if (openerRef.current instanceof HTMLElement) {
        openerRef.current.focus();
      }
    };
  }, [onClose]);

  return (
    <div
      role="dialog"
      aria-modal="true"
      aria-labelledby="employee-dialog-title"
    >
      <h2 id="employee-dialog-title">{employee.name}</h2>
      <p>
        {employee.jobTitle}, {employee.department}
      </p>
      <button type="button" ref={closeButtonRef} onClick={onClose}>
        Close
      </button>
    </div>
  );
}

• document.activeElement is read before focus moves, so the component knows which button opened it. Storing it in a ref rather than state is deliberate: it is not rendered, so changing it should not trigger a render.
• Focus moves to the close button on open. Without this, a keyboard user is still positioned behind the dialog and has to Tab forwards to reach content that appeared in front of them.
• The cleanup function returns focus to the opener. Skipping this is the more common bug: the dialog closes and focus falls back to the top of the document, so the next Tab starts from the beginning of the page.
• Escape closing the dialog is expected behaviour for anything that overlays the page. The listener is on the document because focus may be anywhere inside the dialog.
• role="dialog" with aria-modal="true" tells assistive technology this is a dialog and that content behind it is not currently relevant. aria-labelledby points at the heading, which is how the dialog gets its accessible name without repeating the text.
• One piece is missing on purpose: Tab can still leave the dialog and reach the page behind it. Keeping focus inside needs either the native dialog element with showModal, which the browser traps for you, or a well-tested library. Hand-written focus traps are where this pattern usually goes wrong.

"use client";

import { useEffect, useState } from "react";

type Employee = { id: string; name: string; department: string };
type Status = "idle" | "loading" | "error";

export function EmployeeSearch() {
  const [term, setTerm] = useState("");
  const [status, setStatus] = useState<Status>("idle");
  const [results, setResults] = useState<Employee[]>([]);

  useEffect(() => {
    if (term.trim() === "") {
      setResults([]);
      setStatus("idle");
      return;
    }

    const controller = new AbortController();
    setStatus("loading");

    fetch("/api/employees?search=" + encodeURIComponent(term), {
      signal: controller.signal,
    })
      .then((response) => {
        if (!response.ok) throw new Error("Search failed");
        return response.json();
      })
      .then((employees: Employee[]) => {
        setResults(employees);
        setStatus("idle");
      })
      .catch((error) => {
        if (error.name !== "AbortError") setStatus("error");
      });

    return () => controller.abort();
  }, [term]);

  return (
    <search>
      <label htmlFor="directory-search">Search employees by name</label>
      <input
        id="directory-search"
        type="search"
        value={term}
        onChange={(event) => setTerm(event.target.value)}
      />

      {/* Present from the first render, so changes to its text are announced. */}
      <p role="status">
        {status === "loading" && "Searching"}
        {status === "error" && "Search could not be completed. Try again."}
        {status === "idle" && term !== "" && results.length + " employees found"}
      </p>

      <ul>
        {results.map((employee) => (
          <li key={employee.id}>
            {employee.name} ({employee.department})
          </li>
        ))}
      </ul>
    </search>
  );
}

• role="status" marks a live region with polite announcement: a screen reader reads the new text when the user is between utterances, without interrupting. aria-live="polite" on the element does the same job if you prefer to be explicit.
• The paragraph is in the DOM from the first render, with no text in it. This matters more than it looks: many screen readers do not announce a live region that is added to the page at the same moment as its content, so conditionally rendering the whole element loses the announcement.
• Keep the live region small. Wrapping the whole results list in one means every row is read out on every change, which is unusable for a list of forty employees. A count is enough; the list itself is there to be navigated.
• The text is visible, not hidden. Everyone benefits from knowing the search is running and how many matches there are, and a visible message is far easier to keep accurate than one only some users receive.
• aria-live="assertive" interrupts whatever is being read. Keep it for something the user must act on now, such as a session about to expire. A results count does not qualify.
• AbortController cancels the previous request when the term changes again, so a slow earlier response cannot overwrite a newer one. That is a correctness fix, and it also stops the live region announcing counts for a search the user has moved on from.