aria-modal

Cuándo utilizarlo

En un elemento role="dialog" o role="alertdialog" que deba bloquear la interacción con el resto de la página mientras está abierto. Establezca aria-modal="true" para que el lector de pantalla confine su cursor virtual al diálogo y anuncie el contenido de fondo como inaccesible.

Un diálogo modal tiene tres responsabilidades:

1. aria-modal="true" — informa a la tecnología asistiva que el diálogo es modal.
2. Fondo inerte — aplicado mediante el atributo inert sobre el contenido circundante, o mediante una trampa de foco gestionada con JavaScript. Sin esto, los usuarios de teclado pueden salir del diálogo con Tab.
3. Foco inicial — mueve el foco al interior del diálogo cuando se abre, y lo devuelve al disparador cuando se cierra.

aria-modal solo cubre el aspecto del lector de pantalla; no impide que un usuario de teclado pase por encima del diálogo con Tab. La compatibilidad del navegador para inferir la inercia a partir de aria-modal es inconsistente, por lo que conviene combinar siempre ambas técnicas.

El elemento nativo HTML <dialog> con .showModal() gestiona las tres responsabilidades de forma automática. Prefiera esta opción cuando sea viable.

Cómo mantenerlo sincronizado

Los valores válidos son "true" y "false". Renderice "true" mientras el diálogo está abierto; elimine el atributo o establézcalo en "false" mientras está cerrado (habitualmente el diálogo cerrado ni siquiera está en el DOM, por lo que el atributo carece de relevancia).

aria-modal se combina con dos atributos de etiquetado:

• aria-labelledby="<id-del-título-del-diálogo>" — apunta al encabezado visible.
• aria-describedby="<id-del-cuerpo-del-diálogo>" — opcional, para una descripción breve.

Juntos proporcionan al lector de pantalla un anuncio de apertura coherente: «Diálogo, ¿Eliminar cuenta?, Esta acción no se puede deshacer.»

Errores frecuentes

• aria-modal="true" sin ninguna trampa de foco — los usuarios de teclado llegan hasta el fondo.
• Usar aria-modal en un popover o tooltip no modal. Use role="dialog" solo para diálogos modales auténticos; un popover no es un diálogo.
• Falta aria-labelledby — el lector de pantalla anuncia «Diálogo» sin nombre.
• No mover el foco al interior del diálogo cuando se abre.
• No restaurar el foco al disparador original cuando se cierra.
• Marcar el fondo con aria-hidden="true" en lugar de inert — el foco del teclado sigue escapando; solo el cursor del lector de pantalla queda confinado.
• Dos modales abiertos simultáneamente con aria-modal="true". El árbol de accesibilidad se confunde; muestre uno a la vez.

Ejemplo

<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="confirm-title"
  aria-describedby="confirm-body"
>
  <h2 id="confirm-title">¿Eliminar cuenta?</h2>
  <p id="confirm-body">Esta acción no se puede deshacer.</p>

  <button type="button" autofocus>Cancelar</button>
  <button type="button">Eliminar</button>
</div>