Building an Accessible React Modal Is Harder Than It Looks

Before writing JSX, describe what must happen from the user's point of view.

• Activating the trigger opens the dialog and moves focus to a deliberate place inside it.
• Tab and Shift+Tab remain within the active dialog while it is modal.
• Escape closes only the topmost dismissible dialog.
• Closing returns focus to the element that opened the dialog, or to a sensible fallback if that element no longer exists.
• The dialog has a name, and an optional description, that assistive technology can announce.
• Background content is visually obscured and unavailable for interaction.
• The page behind the dialog does not scroll, while long dialog content remains usable.
• A nested dialog temporarily takes control without corrupting the parent dialog's state or focus history.

That list is the component. The overlay, rounded panel, and animation are only its presentation.

“Focus the first element” sounds reasonable until the first element is a destructive button or an input that opens the software keyboard on a phone.

Choose initial focus from the purpose and shape of the dialog:

• For a short form, focus the first field only when immediate typing is the expected next action.
• For a destructive confirmation, focus the least destructive action, usually Cancel.
• For a long or highly structured dialog, focus a static heading or introductory element with `tabIndex={-1}` so reading starts at the top without skipping content.
• For a simple choice, focus the most likely safe action.
• When touch opened the dialog, consider whether focusing an input would cover important context with the virtual keyboard.

The component API therefore needs more than an `open` boolean. It needs a way for the feature using the dialog to nominate the correct initial target.

type ModalProps = {
  initialFocusRef?: RefObject<HTMLElement | null>;
  open: boolean;
  onDismiss: () => void;
  triggerRef?: RefObject<HTMLElement | null>;
};

useLayoutEffect(() => {
  if (!open) return;

  const frame = requestAnimationFrame(() => {
    const target = initialFocusRef?.current ?? dialogRef.current;
    target?.focus();
  });

  return () => cancelAnimationFrame(frame);
}, [initialFocusRef, open]);

This fallback focuses the dialog container, which has `tabIndex={-1}`. It is safer than leaving focus behind the overlay, but it is not a substitute for choosing the right target for a real workflow.

Escape support is easy with one modal and easy to break with two. A document-level listener attached by every open dialog can close the entire stack from one keypress.

Each dialog needs an identity, and a shared layer manager must know which identity is currently on top.

const modalStack: symbol[] = [];

export function pushModal(id: symbol) {
  modalStack.push(id);
}

export function removeModal(id: symbol) {
  const index = modalStack.lastIndexOf(id);
  if (index >= 0) modalStack.splice(index, 1);
}

export function isTopModal(id: symbol) {
  return modalStack.at(-1) === id;
}

The keyboard handler can then ignore events belonging to a higher layer.

useEffect(() => {
  if (!open) return;

  function onKeyDown(event: KeyboardEvent) {
    const dialog = dialogRef.current;
    if (!dialog || !isTopModal(layerId.current)) return;

    if (event.key === "Escape") {
      event.preventDefault();
      event.stopPropagation();
      onDismiss();
      return;
    }

    keepTabInside(event, dialog);
  }

  document.addEventListener("keydown", onKeyDown, true);
  return () => document.removeEventListener("keydown", onKeyDown, true);
}, [onDismiss, open]);

Escape is only one exit. Every modal should also contain a visible close, cancel, or completion control. A touch screen-reader user cannot depend on a physical Escape key.

Some workflows need to protect unsaved work. Do not silently disable Escape and leave the user trapped. Let Escape request closure, then present an understandable confirmation path with an explicit way to remain or leave.

React portals let a dialog escape ancestors with `overflow: hidden`, transforms, and local stacking contexts. The dialog can render under a stable container near the document body while remaining a child of the same React tree.

if (!open) return null;

return createPortal(
  <div className="modal-layer" role="presentation">
    <div className="modal-backdrop" />
    <div
      aria-labelledby={titleId}
      aria-modal="true"
      ref={dialogRef}
      role="dialog"
      tabIndex={-1}
    >
      {children}
    </div>
  </div>,
  document.body,
);

The physical DOM position changes; the React relationship does not. Context still works, and events from portal content still bubble through the React tree. A click inside the modal can therefore reach an ancestor React handler even though the DOM nodes are far apart. Backdrop dismissal and parent click handlers need deliberate event boundaries.

A portal also does not make the background inert. For a custom ARIA dialog, the modal manager must disable all content outside the active layer while preserving any pre-existing `inert` or `aria-hidden` state. That bookkeeping becomes more difficult when several React roots, third-party overlays, or nested dialogs share the page.

Imagine an edit-profile modal that opens a second dialog to confirm discarding changes. While the confirmation is open:

• The confirmation is the only active modal.
• Focus is trapped inside the confirmation, not the parent.
• Escape closes only the confirmation.
• The parent remains mounted but is not interactive.
• Page scrolling remains locked after the confirmation closes.
• Focus returns to the control in the parent that opened the confirmation.
• Closing the parent later restores focus to the original page trigger.

That behavior requires a stack of focus scopes, layer identities, inert regions, and scroll locks. Z-index establishes only paint order. Two independent modal components can look correctly stacked while both listen for Escape, both fight to restore focus, and both believe they own the body styles.

Avoid nested dialogs when the interaction can become one clearer flow. A confirmation can sometimes replace the parent dialog's contents, or an inline warning can keep the decision in context. When nesting expresses a real hierarchy, use one overlay system that coordinates every layer.

Building the educational version is useful because it reveals the contract. Shipping that version as shared infrastructure is a different decision.

An established accessible component library is usually safer when the application has any of these conditions:

• More than one dialog or more than one team consuming the primitive.
• Nested dialogs, menus that open dialogs, popovers inside dialogs, or other overlay combinations.
• Server rendering, hydration, exit animations, or portals into custom containers.
• Complex forms with dynamic fields, validation, asynchronous state, or destructive actions.
• Mobile Safari, touch screen readers, zoomed layouts, or virtual keyboards in the support matrix.
• A design system that needs consistent modal behavior across several products.
• No dedicated capacity to maintain focus, inertness, scroll, and browser edge cases over time.

Libraries such as React Aria Components, Radix Primitives, Base UI, and Ariakit have already invested in focus scopes, dismissal, portals, and overlay coordination. The important selection criteria are not screenshots or default styles. Review the keyboard contract, accessible naming API, nested-overlay behavior, scroll strategy, server-rendering support, maintenance history, bundle cost, and the ease of applying your own semantic design tokens.

A library does not make the finished feature accessible by itself. The team must still provide a useful title, choose appropriate initial and restored focus, preserve visible close controls, write understandable validation messages, and test the actual content. The library takes ownership of difficult infrastructure; the product team keeps ownership of meaning.