Modal accesible con dialog de HTML: lo que el navegador ya hace por ti
En la práctica/ 14 min de lectura
showModal() ya mueve el foco, deja inerte la página, cierra con Escape y dibuja un ::backdrop. Código completo en HTML y React, probado en Chromium, y lo que te toca a ti.
- JavaScript
- React
En este artículo (8)
Un modal accesible no necesita librería: el elemento <dialog> abierto con showModal() ya mueve el foco dentro, deja inerte el resto de la página, se cierra con Escape, se dibuja encima de todo con su ::backdrop y, al cerrarse, devuelve el foco al elemento que lo tenía. A ti te toca el título y un botón para cerrar.
Aquí verás qué hace el navegador según la referencia de <dialog> en MDN y el estándar HTML, un ejemplo completo en HTML y en React con useRef, y lo que comprobamos con Playwright en Chromium, incluido un matiz sobre adónde vuelve el foco que la frase de siempre pasa por alto.
Qué te da showModal() en un modal sin JavaScript extra
<dialog> es Baseline «ampliamente disponible» desde marzo de 2022, según MDN. Tiene dos formas de abrirse y solo una es un modal: showModal() abre un diálogo modal y show(), uno no modal que deja usar el resto de la página. Con showModal() recibes, sin escribir nada más:
- La capa superior. Según la página de showModal() en MDN, el diálogo se muestra en la top layer, encima de cualquier otro elemento, con un pseudoelemento
::backdropdetrás. Sin pelear conz-index. - El resto de la página inerte. Todo lo que no es el diálogo ni sus descendientes queda inerte «como si tuviera el atributo
inert»: no recibe clics ni foco. Solo se bloquea el documento que contiene el diálogo; si vive dentro de un iframe, la página de afuera sigue activa. - Cierre con Escape. Escape dispara
cancely luegoclose. Si hay varios modales abiertos, se cierra solo el último. - La semántica. MDN indica que un
<dialog>abierto conshowModal()tienearia-modal="true"implícito, y su rol implícito esdialog. - Formularios que cierran. Un
<form method="dialog">dentro del diálogo lo cierra al enviarse, sin mandar nada al servidor, y deja enreturnValueelvaluedel botón que lo envió.
Desliza la figura para verla completa
Una librería de modal típica resuelve esa lista en JavaScript: portal, trampa de foco, aria-hidden, listener de teclado, overlay. Con <dialog> lo hace el navegador. Lo que no hace es darle nombre al diálogo ni un botón visible para cerrar: eso sigue siendo tuyo.
Foco, fondo inactivo y cierre con Escape
Al abrir. El estándar define los «pasos de foco del diálogo»: si el propio <dialog> tiene autofocus, enfoca el diálogo; si no, busca su delegado de foco (el descendiente con autofocus o, si no hay, el primer elemento enfocable en orden del documento); y si no encuentra ninguno, enfoca el diálogo. MDN recomienda autofocus en el control que el usuario va a usar primero. En nuestra prueba, un diálogo con solo texto se enfocó a sí mismo.
Al cerrar. Aquí está el matiz. La frase habitual es «el foco vuelve al botón que lo abrió», y no es exactamente lo que dice el estándar. show() y showModal() guardan el elemento que tenía el foco justo antes de abrir (el previously focused element). Al cerrar, el navegador vuelve a enfocar ese elemento si el diálogo era modal o si el foco estaba dentro, y sin hacer scroll. La referencia de <dialog> en MDN no describe este paso; la del rol dialog de ARIA en MDN pide lo mismo: devolver el foco a donde estaba antes de entrar al diálogo. En la práctica:
- Si el usuario hace clic en el botón y el navegador le da el foco, el foco vuelve al botón. En Chromium 151 pasó así.
- Si abres el modal por código, por ejemplo con un temporizador, el foco vuelve a lo que estaba enfocado entonces. En nuestra prueba volvió al buscador, no a ningún botón.
- Si el botón desapareció mientras el modal estaba abierto, no hay adónde volver y el foco cae en
body. - MDN advierte en su página de <button> que Safari, por diseño, no le da el foco a un botón al hacerle clic. Ahí el elemento guardado es el que tuviera el foco antes del clic. No lo probamos en Safari.
El fondo. Mientras el modal está abierto, la página de atrás no responde. Lo comprobamos: llamar focus() en un botón del fondo no movió el foco, y un clic real en sus coordenadas cayó en el diálogo (elementFromPoint devolvió el <dialog>). Con Tab, el foco recorrió Cancelar, Quitar, salió del documento (document.activeElement pasó a body) y volvió a Cancelar, sin tocar nunca el carrito.
Escape. Una petición de cierre dispara cancel, que se puede cancelar con preventDefault(), y después close. Según la página del evento cancel en MDN, pueden dispararla Escape en escritorio, requestClose() y el botón de atrás en móviles. close() cierra sin pasar por cancel y no se puede impedir. requestClose() es más nuevo: Baseline desde mayo de 2025. Un diálogo abierto con show() no se cierra con Escape.
| Comportamiento | showModal() | show() |
|---|---|---|
Capa superior y ::backdrop | Sí | No |
| Resto de la página inerte | Sí | No: se puede enfocar y hacer clic atrás |
| Escape lo cierra | Sí: cancel y luego close | No |
| Foco al abrir | Pasos de foco del diálogo | Los mismos pasos |
| Foco al cerrar | Al elemento que tenía el foco antes de abrir | Al mismo, solo si el foco estaba dentro |
Coincide con :modal | Sí | No |
aria-modal implícito | true | false |
Desliza la figura para verla completa
Lo que no hace ninguno de los dos por defecto es cerrarse con un clic fuera. Para eso existe el atributo closedby="any", pero según la página de closedBy en MDN tiene disponibilidad limitada: los datos de compatibilidad de MDN lo dan en Chrome y Edge 134, Firefox 141, y en Safari solo en la versión preliminar (Technology Preview), no en iOS. En Chromium 151, un clic en el fondo cerró el diálogo con closedby="any" y no lo cerró sin él.
Estilos del dialog con ::backdrop
::backdrop es una caja del tamaño de la ventana que se dibuja justo debajo del elemento en la capa superior, y solo existe cuando abres con showModal(). Estas son las tres reglas del ejemplo:
dialog { max-width: min(28rem, calc(100% - 2rem)); padding: 1.5rem; border: 1px solid #d4d4d4; border-radius: 12px; }
dialog::backdrop { background: rgb(0 0 0 / 0.55); }
html:has(dialog:modal) { overflow: hidden; }
- La caja del diálogo: ancho máximo de 28rem que nunca toca los bordes en un celular, relleno y borde. No le pongas
displayaquí: en nuestra prueba,dialog { display: flex; }dejó visible un diálogo cerrado, porque pisa eldisplay: nonedel navegador. Si necesitas flex, usadialog[open]. - El fondo que oscurece la página. Como el resto de la página está inerte, el
::backdropsolo es visual. - Bloquea el scroll de la página mientras hay un modal abierto. Hace falta: el diálogo no lo impide. Sin esta regla, con el modal abierto, la rueda del mouse movió la página 800 px y la tecla Av Pág otros 525; con ella, 0.
:has()es Baseline desde diciembre de 2023 y:modal, desde septiembre de 2022, según MDN.
Ejemplo completo (HTML y React con ref)
El caso: un carrito con un botón Quitar que pide confirmación. Toca lo importante: nombre accesible, foco inicial, returnValue y el foco cuando el botón de origen desaparece. Este es el archivo completo, sin dependencias:
<!doctype html>
<html lang="es">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Tu carrito</title>
<style>
dialog { max-width: min(28rem, calc(100% - 2rem)); padding: 1.5rem; border: 1px solid #d4d4d4; border-radius: 12px; }
dialog::backdrop { background: rgb(0 0 0 / 0.55); }
html:has(dialog:modal) { overflow: hidden; }
</style>
</head>
<body>
<h1 id="cart-title" tabindex="-1">Tu carrito</h1>
<ul id="cart">
<li id="item-1">Tenis Runner, talla 27
<button type="button" class="remove" data-item="item-1">Quitar</button>
</li>
</ul>
<dialog id="confirm-remove" aria-labelledby="confirm-title">
<form method="dialog">
<h2 id="confirm-title">¿Quitar este producto del carrito?</h2>
<p>Puedes volver a agregarlo después.</p>
<button value="cancel" autofocus>Cancelar</button>
<button value="remove">Quitar</button>
</form>
</dialog>
<script>
const dialog = document.getElementById("confirm-remove");
let pending = null;
document.getElementById("cart").addEventListener("click", (event) => {
const button = event.target.closest(".remove");
if (!button) return;
pending = document.getElementById(button.dataset.item);
dialog.returnValue = "";
dialog.showModal();
});
dialog.addEventListener("close", () => {
if (dialog.returnValue === "remove") {
pending.remove();
document.getElementById("cart-title").focus();
}
pending = null;
});
</script>
</body>
</html>
- El
<style>son las tres reglas de la sección anterior. - El
h1tienetabindex="-1"para poder recibir el foco desde el script sin entrar en el orden de Tab. - Cada Quitar es
type="button"y nombra su fila condata-item. - El
<dialog>llevaaria-labelledby="confirm-title": su nombre accesible es el texto delh2. - El
<form method="dialog">envuelve el contenido. Sus dos botones son de tipo submit por defecto: cualquiera de los dos cierra el diálogo y deja suvalueenreturnValue. autofocusestá en Cancelar, la opción segura: si el usuario pulsa Enter sin leer, no se borra nada.- El listener del
ulatiende a todos los botones conclosest(".remove"), guarda la fila enpending, ponereturnValueen vacío y abre conshowModal(). - El reinicio de
returnValueimporta: según el estándar y la página de returnValue en MDN, Escape no lo cambia, así que podría quedar el"remove"de una confirmación anterior. El ejemplo de MDN hace lo mismo antes de cada apertura. closellega siempre, se cierre como se cierre. Si la respuesta fue"remove", borra la fila.- El navegador ya devolvió el foco a Quitar, pero ese botón se va con la fila. Sin el
focus()alh1, el foco caería enbody.
En React, la idea es la misma: un ref al <dialog> y los métodos del navegador. El componente usa useRef y onClick, así que en Next.js necesita "use client"; si dudas dónde ponerlo, revisa dónde poner use client en Next.js.
"use client";
import { useId, useRef, useState } from "react";
function RemoveButton({ name, onRemove }: { name: string; onRemove: () => void }) {
const dialogRef = useRef<HTMLDialogElement>(null);
const titleId = useId();
function open() {
const dialog = dialogRef.current;
if (!dialog) return;
dialog.returnValue = "";
dialog.showModal();
}
function handleClose() {
if (dialogRef.current?.returnValue === "remove") onRemove();
}
return (
<>
<button type="button" onClick={open}>Quitar</button>
<dialog ref={dialogRef} aria-labelledby={titleId} onClose={handleClose}>
<form method="dialog">
<h2 id={titleId}>¿Quitar {name} del carrito?</h2>
<p>Puedes volver a agregarlo después.</p>
<button value="cancel">Cancelar</button>
<button value="remove">Quitar</button>
</form>
</dialog>
</>
);
}
export function Cart() {
const [items, setItems] = useState([{ id: "1", name: "Tenis Runner, talla 27" }]);
const headingRef = useRef<HTMLHeadingElement>(null);
function remove(id: string) {
setItems((list) => list.filter((item) => item.id !== id));
headingRef.current?.focus();
}
return (
<section>
<h1 ref={headingRef} tabIndex={-1}>Tu carrito</h1>
<ul>
{items.map((item) => (
<li key={item.id}>
{item.name} <RemoveButton name={item.name} onRemove={() => remove(item.id)} />
</li>
))}
</ul>
</section>
);
}
"use client"marca el archivo como componente de cliente en Next.js; fuera de Next.js no hace nada.dialogRefapunta al<dialog>, yuseId()genera un id único para el título, porque cada fila del carrito tiene su propio diálogo.open()reiniciareturnValuey llamashowModal(). No hay estadoisOpen: el navegador ya sabe si está abierto.onClosees el eventoclosedel navegador, que React expone para<dialog>según su documentación de componentes comunes. Ahí se leereturnValue.- Cancelar va primero a propósito y no lleva
autoFocus. React enfoca unautoFocus«al montar», cuando el diálogo todavía está cerrado, y en nuestra prueba con React 19.0.0 no escribió el atributoautofocusen el DOM; al abrir, el navegador enfocó el primer botón. Si necesitas otro control, llama sufocus()después deshowModal(). Cartborra el producto y mueve el foco alh1, igual que en la versión HTML, porque la fila y su botón desaparecen.
No uses <dialog open={isOpen}>: el atributo open abre un diálogo no modal. En nuestra prueba quedó abierto, pero sin coincidir con :modal: un diálogo no modal, sin página inerte ni cierre con Escape. Si prefieres manejarlo con estado, un efecto que llame showModal() y close() es un uso legítimo (sincronizar con una API del navegador), al contrario que los datos derivados con useEffect.
Corrimos los dos ejemplos con Playwright 1.62 en Chromium 151, en español y en inglés: 72 comprobaciones, todas en verde. Estas son seis líneas de la salida de la versión HTML en español:
PASS focus moved inside the dialog (autofocus button) (button:Cancelar)
PASS click on the background button does nothing (elementFromPoint -> #confirm-remove)
PASS Escape fires cancel, then close (cancel(cancelable=true),close)
PASS focus back on the opener (it had focus when showModal ran) (button:Quitar)
PASS form method="dialog": returnValue is the button value (remove)
PASS programmatic open: focus returns to the previously focused #search (input#search)
- Al abrir, el foco está en Cancelar, el de
autofocus. - Un clic sobre el Quitar del fondo cae en el
<dialog>. - Escape:
cancel(cancelable) y luegoclose. - El foco vuelve a Quitar, que lo tenía al llamar
showModal(). - Quitar, dentro del diálogo, deja
"remove"enreturnValue. - En otra página, un modal abierto por código devolvió el foco al buscador.
Lo que sí tienes que cuidar: título y botón de cerrar
El nombre. El navegador expone el <dialog> con rol dialog, pero no inventa su nombre. La página del rol dialog en MDN lo recomienda con fuerza y propone aria-labelledby apuntando al título visible, más aria-describedby si hay un texto que lo explique. Sin título visible, usa aria-label.
El botón de cerrar. Escape no es un control visible y en un celular no hay tecla Escape. Pon siempre un <button> de verdad que cierre: en una confirmación, Cancelar; en un modal informativo, Cerrar. Si es un icono, dale nombre con aria-label="Cerrar". Si el formulario tiene campos required, el botón de cancelar necesita formnovalidate o una llamada a close(): MDN explica que, sin eso, la validación no deja cerrar el diálogo.
Desliza la figura para verla completa
Y no le pongas tabindex al <dialog>: tanto MDN como el estándar lo prohíben. Si el modal lleva un formulario, por ejemplo para capturar un correo o una dirección, aplica lo mismo que en el checkout móvil con autocomplete y el teclado correcto: autocomplete, type e inputmode deciden si el usuario escribe en un toque o en un minuto.
Errores comunes
- Abrir con el atributo
open(o<dialog open>en React). MDN lo desaconseja: queda no modal. - Usar
show()para un modal.show()es no modal: la página de atrás sigue activa y Escape no lo cierra. - Dar por hecho que el foco vuelve al botón. Vuelve al elemento que tenía el foco al abrir. Si lo abres por código, o si el botón desaparece, decide tú adónde va el foco.
- No reiniciar
returnValue. La respuesta anterior puede colarse tras un Escape. En Chromium 151 vimos"", pero el estándar no lo garantiza: reinícialo antes de cadashowModal(). - Confiar en
autoFocusde React. Enfoca al montar, con el diálogo cerrado. - Poner
displayen el selectordialog. El diálogo cerrado se vuelve visible. Usadialog[open]. - Olvidar el scroll del fondo. La página sigue desplazándose con el modal abierto hasta que le pones
overflow: hidden. - Bloquear Escape siempre. Llamar
preventDefault()en cadacanceldeja al usuario sin salida por teclado. Úsalo solo para avisar de cambios sin guardar.
Preguntas frecuentes
¿Necesito una trampa de foco con un modal hecho con dialog?
No. Con showModal(), el resto del documento queda inerte, así que Tab solo recorre los controles del diálogo y, al final, sale de la página hacia el navegador. En nuestra prueba nunca llegó a un elemento de la página de atrás.
¿Cómo lo cierro con un clic fuera?
Con closedby="any", en los navegadores que lo soportan: Chrome y Edge 134 o superior y Firefox 141 o superior, según los datos de MDN; Safari solo lo tiene en su versión preliminar. Donde no está, el clic fuera no hace nada. Para la accesibilidad no es necesario: Escape y un botón visible bastan.
¿Tengo que poner role="dialog" o aria-modal="true"?
No. El rol implícito de <dialog> es dialog, y MDN indica que, abierto con showModal(), tiene aria-modal="true" implícito. Lo que sí tienes que añadir es el nombre, con aria-labelledby o aria-label.
¿Funciona en todos los navegadores?
<dialog>, showModal(), close() y ::backdrop son Baseline desde marzo de 2022. requestClose() lo es desde mayo de 2025. closedby todavía tiene disponibilidad limitada, así que trátalo como una mejora opcional.
Checklist
- Abres con
showModal(), no conshow()ni con el atributoopen. - El
<dialog>tiene nombre:aria-labelledbyal título visible oaria-label. - Hay un botón visible para cerrar, con texto o con
aria-label. autofocusestá en el control que el usuario necesita primero; en una confirmación, la opción segura.- Los botones del formulario usan
method="dialog"y unvaluedistinto, y reiniciasreturnValueantes de abrir. - Si el botón que abrió el modal puede desaparecer, mueves el foco a un lugar con sentido al cerrar.
- El fondo tiene estilo con
::backdropy no se desplaza:html:has(dialog:modal) { overflow: hidden; }. - No hay
tabindexen el<dialog>nidisplayen el selectordialog. - Probaste con teclado: Tab, Escape y adónde vuelve el foco.
Con esto, el modal hace lo que hacía tu librería, sin una sola dependencia. Si el modal recoge datos, revisa también cómo configurar autocomplete y el teclado en el checkout móvil. Y si lo vas a montar en React, evita los efectos que no necesitas: calcula los datos derivados en el render.
¿Viste esto en Instagram? Comenta DIALOG en el Reel y te mando la guía.
Escrito por

Publicado el 3 de noviembre de 2026