Crear un modal accesible en React es más difícil de lo que parece

Antes de escribir JSX, describe qué debe ocurrir desde el punto de vista de la persona usuaria.

• Al activar el disparador se abre el diálogo y el foco se mueve a un lugar elegido dentro de él.
• Tab y Mayús+Tab permanecen dentro del diálogo activo mientras sea modal.
• Escape cierra solo el diálogo descartable que está en la parte superior.
• Al cerrar, el foco vuelve al elemento que abrió el diálogo o a una alternativa razonable si ese elemento ya no existe.
• El diálogo tiene un nombre y, opcionalmente, una descripción que las tecnologías de asistencia pueden anunciar.
• El contenido del fondo queda visualmente oculto y no admite interacción.
• La página detrás del diálogo no se desplaza, pero el contenido largo del propio diálogo sigue siendo utilizable.
• Un diálogo anidado toma el control temporalmente sin corromper el estado ni el historial de foco del diálogo padre.

Esa lista es el componente. La superposición, el panel redondeado y la animación son solo su presentación.

«Enfoca el primer elemento» suena razonable hasta que ese primer elemento es un botón destructivo o un campo que abre el teclado virtual en un teléfono.

Elige el foco inicial según el propósito y la forma del diálogo:

• En un formulario corto, enfoca el primer campo solo cuando escribir de inmediato sea la siguiente acción esperada.
• En una confirmación destructiva, enfoca la acción menos destructiva, normalmente Cancelar.
• En un diálogo largo o muy estructurado, enfoca un encabezado estático o un elemento introductorio con `tabIndex={-1}` para que la lectura empiece arriba sin saltarse contenido.
• En una elección sencilla, enfoca la acción segura más probable.
• Cuando una interacción táctil haya abierto el diálogo, valora si enfocar un campo ocultaría contexto importante con el teclado virtual.

Por tanto, la API del componente necesita algo más que un booleano `open`. Debe permitir que la funcionalidad que utiliza el diálogo designe el objetivo inicial correcto.

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]);

Esta alternativa enfoca el contenedor del diálogo, que tiene `tabIndex={-1}`. Es más segura que dejar el foco detrás de la superposición, pero no sustituye la elección del objetivo adecuado para un flujo real.

Admitir Escape es sencillo con un solo modal y fácil de romper con dos. Un listener a nivel de documento instalado por cada diálogo abierto puede cerrar toda la pila con una única pulsación.

Cada diálogo necesita una identidad, y un gestor de capas compartido debe saber qué identidad está actualmente en la parte superior.

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;
}

El manejador del teclado puede ignorar entonces los eventos que pertenecen a una capa superior.

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 es solo una salida. Todo modal debe incluir también un control visible para cerrar, cancelar o completar. Una persona que usa un lector de pantalla táctil no puede depender de una tecla Escape física.

Algunos flujos deben proteger trabajo no guardado. No deshabilites Escape en silencio dejando a la persona atrapada. Permite que Escape solicite el cierre y presenta después una confirmación comprensible con una forma explícita de quedarse o salir.

Los portales de React permiten que un diálogo escape de ancestros con `overflow: hidden`, transformaciones y contextos de apilamiento locales. El diálogo puede renderizarse bajo un contenedor estable cercano al body del documento y seguir siendo hijo del mismo árbol de React.

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,
);

Cambia la posición física en el DOM, pero no la relación en React. El contexto sigue funcionando y los eventos del portal continúan propagándose por el árbol de React. Por tanto, un clic dentro del modal puede alcanzar un manejador React ancestro aunque los nodos DOM estén muy separados. El cierre al pulsar el fondo y los manejadores de clic del padre necesitan límites de evento deliberados.

Un portal tampoco vuelve inerte el fondo. En un diálogo ARIA personalizado, el gestor modal debe deshabilitar todo el contenido fuera de la capa activa y conservar cualquier estado `inert` o `aria-hidden` previo. Esa contabilidad se complica cuando varias raíces de React, overlays de terceros o diálogos anidados comparten la página.

Imagina un modal para editar un perfil que abre un segundo diálogo para confirmar que se descartan los cambios. Mientras la confirmación está abierta:

• La confirmación es el único diálogo activo.
• El foco queda contenido dentro de la confirmación, no en el diálogo padre.
• Escape cierra solo la confirmación.
• El padre permanece montado, pero no admite interacción.
• El scroll de la página continúa bloqueado cuando se cierra la confirmación.
• El foco vuelve al control del padre que abrió la confirmación.
• Al cerrar posteriormente el padre, el foco se restaura al disparador original de la página.

Ese comportamiento exige una pila de ámbitos de foco, identidades de capa, regiones inertes y bloqueos del scroll. El z-index solo establece el orden de pintado. Dos componentes modales independientes pueden parecer bien apilados mientras ambos escuchan Escape, compiten por restaurar el foco y creen ser dueños de los estilos del body.

Evita diálogos anidados cuando la interacción pueda convertirse en un único flujo más claro. A veces una confirmación puede sustituir el contenido del diálogo padre, o un aviso en línea puede mantener la decisión en su contexto. Cuando el anidamiento representa una jerarquía real, utiliza un único sistema de overlays que coordine todas las capas.

Construir la versión educativa es útil porque revela el contrato. Entregar esa misma versión como infraestructura compartida es una decisión distinta.

Una biblioteca consolidada de componentes accesibles suele ser más segura cuando la aplicación presenta cualquiera de estas condiciones:

• Más de un diálogo o más de un equipo consume la primitiva.
• Existen diálogos anidados, menús que abren diálogos, popovers dentro de diálogos u otras combinaciones de overlays.
• El sistema incluye renderizado en servidor, hidratación, animaciones de salida o portales hacia contenedores personalizados.
• Hay formularios complejos con campos dinámicos, validación, estados asíncronos o acciones destructivas.
• Safari móvil, los lectores de pantalla táctiles, los layouts con zoom o los teclados virtuales forman parte de la matriz de soporte.
• Un sistema de diseño necesita un comportamiento modal coherente en varios productos.
• No hay capacidad dedicada para mantener a lo largo del tiempo el foco, la inercia, el scroll y los casos límite de los navegadores.

Bibliotecas como React Aria Components, Radix Primitives, Base UI y Ariakit ya han invertido en ámbitos de foco, cierre, portales y coordinación de overlays. Los criterios importantes no son las capturas de pantalla ni los estilos predeterminados. Revisa el contrato de teclado, la API de nombres accesibles, el comportamiento de los overlays anidados, la estrategia de scroll, el soporte para renderizado en servidor, el historial de mantenimiento, el coste en el bundle y la facilidad para aplicar tus propios tokens semánticos de diseño.

Una biblioteca no vuelve accesible por sí sola la funcionalidad terminada. El equipo debe proporcionar un título útil, elegir el foco inicial y restaurado apropiados, mantener controles de cierre visibles, escribir mensajes de validación comprensibles y comprobar el contenido real. La biblioteca se hace cargo de la infraestructura difícil; el equipo de producto conserva la responsabilidad sobre el significado.