Accessible modal dialog

Why this pattern keeps breaking

Modal dialogs are the most common custom widget on the web and the most common one to fail accessibility review. The visual pattern is straightforward — overlay, centred panel, close button. The behavioural contract is what trips up almost every implementation: focus has to move into the dialog, get trapped there until close, and return to the trigger when the dialog dismisses. Escape has to close it. The page behind has to be inert to assistive tech. Get any of those wrong and a keyboard or screen-reader user is stuck in a layer of UI they can't escape or understand.

How AI coding tools fail this

Ask any AI assistant for "a modal" and you will get a styled <div> overlay with a close button. The visual is correct. The accessibility contract — role="dialog", aria-modal="true", focus trap, focus return, Escape handler, page-behind inert — is missing entirely or partially implemented in a way that fails one of the corners.

The most common shipped failures:

Focus stays on the triggering button when the modal opens, so a screen-reader user has no idea anything happened.
Tab cycles out of the modal into the page behind, with no return.
Escape closes the modal but focus jumps to <body> instead of back to the triggering button — the user loses their place.
The page behind is visible to assistive tech, so screen-reader users can navigate "into" content they can't actually see or interact with.
The overlay click closes the modal but Escape doesn't (or vice versa), creating an inconsistent dismissal contract.

Canonical implementation

The right answer for most product teams: use a vetted library. The WAI ARIA Authoring Practices Guide describes the contract; the leading React libraries implement it correctly. Radix UI Dialog (opens in new tab), Headless UI Dialog (opens in new tab), and React Aria Dialog (opens in new tab) all ship the focus management, ARIA attributes, and Escape handling correctly out of the box.

A minimal Radix-based dialog that meets the contract:

import * as Dialog from "@radix-ui/react-dialog";

export function ConfirmDelete({ onConfirm }: { onConfirm: () => void }) {
  return (
    <Dialog.Root>
      <Dialog.Trigger asChild>
        <button>Delete project</button>
      </Dialog.Trigger>

      <Dialog.Portal>
        <Dialog.Overlay className="fixed inset-0 bg-black/50" />
        <Dialog.Content className="fixed inset-0 m-auto h-fit max-w-sm rounded-lg bg-background p-6">
          <Dialog.Title className="text-lg font-semibold">
            Delete this project?
          </Dialog.Title>
          <Dialog.Description className="mt-2 text-sm text-muted-foreground">
            This cannot be undone. The project history will also be
            removed.
          </Dialog.Description>

          <div className="mt-6 flex justify-end gap-3">
            <Dialog.Close asChild>
              <button>Cancel</button>
            </Dialog.Close>
            <button onClick={onConfirm}>Delete</button>
          </div>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

This satisfies all the requirements: focus moves into the dialog on open, traps inside, returns to the trigger on close. Escape closes. role="dialog" and aria-modal="true" are applied automatically. Dialog.Title is wired as the accessible name; Dialog.Description as the description. The overlay is dismissible. The page behind is inert to assistive tech via aria-hidden on siblings.

Failing example

A hand-rolled modal that misses the contract:

function Modal({ open, onClose, children }) {
  if (!open) return null;
  return (
    <div className="fixed inset-0 bg-black/50">
      <div className="m-auto w-fit bg-white p-6">
        <button onClick={onClose}>Close</button>
        {children}
      </div>
    </div>
  );
}

What's missing: role="dialog", aria-modal, accessible name (no aria-labelledby), focus is not moved into the dialog on open, focus is not trapped, Escape does not close it, focus does not return to the trigger, page behind is not inert, the overlay click is not wired to close. Visually correct. Accessibility-broken in seven distinct ways.

Minimum viable hand-roll

If you can't reach for a library, this is the minimum that gets the core contract right (role, labelling, focus move on open, focus return on close, Escape to dismiss). It is not a complete implementation — see the disclaimer below.

import { useEffect, useRef } from "react";

function Modal({
  open,
  onClose,
  titleId,
  children,
}: {
  open: boolean;
  onClose: () => void;
  titleId: string;
  children: React.ReactNode;
}) {
  const triggerRef = useRef<HTMLElement | null>(null);
  const dialogRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!open) return;
    triggerRef.current = document.activeElement as HTMLElement;
    dialogRef.current?.focus();

    function onKey(e: KeyboardEvent) {
      if (e.key === "Escape") onClose();
    }
    document.addEventListener("keydown", onKey);
    return () => {
      document.removeEventListener("keydown", onKey);
      triggerRef.current?.focus();
    };
  }, [open, onClose]);

  if (!open) return null;
  return (
    <div
      role="dialog"
      aria-modal="true"
      aria-labelledby={titleId}
      ref={dialogRef}
      tabIndex={-1}
      className="fixed inset-0 m-auto h-fit w-fit bg-background p-6"
    >
      {children}
    </div>
  );
}

This still doesn't handle Tab cycling within the modal — for that you need a focus-trap library (focus-trap-react) or the full ARIA APG implementation. For production, use Radix or Headless UI. This example exists to show the minimum contract, not to be copy-pasted.

Verification checklist

Before shipping any dialog, manually verify each of these:

Tab into the trigger, press Enter — focus moves into the dialog.
Tab repeatedly inside the dialog — focus cycles through dialog controls only, never reaching the page behind.
Press Escape — dialog closes, focus returns to the original trigger.
Click the overlay — dialog closes, focus returns to the trigger.
With a screen reader running, open the dialog — the dialog title is announced, and only dialog content is reachable.
Resize the viewport to mobile width — the dialog remains scrollable and dismissible.

Why this pattern keeps breaking

How AI coding tools fail this

Canonical implementation

Verification checklist

WCAG criteria this pattern satisfies

References