Saltar al contenido

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)
  1. Qué te da showModal() en un modal sin JavaScript extra
  2. Foco, fondo inactivo y cierre con Escape
  3. Estilos del dialog con ::backdrop
  4. Ejemplo completo (HTML y React con ref)
  5. Lo que sí tienes que cuidar: título y botón de cerrar
  6. Errores comunes
  7. Preguntas frecuentes
  8. Checklist

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 ::backdrop detrás. Sin pelear con z-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 cancel y luego close. Si hay varios modales abiertos, se cierra solo el último.
  • La semántica. MDN indica que un <dialog> abierto con showModal() tiene aria-modal="true" implícito, y su rol implícito es dialog.
  • Formularios que cierran. Un <form method="dialog"> dentro del diálogo lo cierra al enviarse, sin mandar nada al servidor, y deja en returnValue el value del botón que lo envió.
lo que una librería de modal escribe en JSqué hace faltalibrería típica (JS)<dialog> + showModal()encima de todoportal + z-indexcapa superior (top layer)página de fondofocus trap + aria-hiddeninerte, sin códigoEscapelistener de keydowncancel y luego closefoco al abrirfocus() a manoautofocus o primer controlfoco al cerrarguardarlo y restaurarlovuelve al foco anteriorfondo oscuroun div extra::backdropnombre accesiblearia-labelledbyaria-labelledby (tuyo)la misma lista, sin dependenciasel nombre del dialog y el botón de cerrar siguen siendo tuyos en los dos casos

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.

ComportamientoshowModal()show()
Capa superior y ::backdropSíNo
Resto de la página inerteSíNo: se puede enfocar y hacer clic atrás
Escape lo cierraSí: cancel y luego closeNo
Foco al abrirPasos de foco del diálogoLos mismos pasos
Foco al cerrarAl elemento que tenía el foco antes de abrirAl mismo, solo si el foco estaba dentro
Coincide con :modalSíNo
aria-modal implícitotruefalse
showModal() contra show(), comportamiento por comportamientocomportamientoshowModal()show()capa superior + ::backdropsínoresto de la página inertesínoEscape (cancel → close)sínofoco al abrirautofocus › primero › dialoglos mismos pasosfoco al cerrarel que tenía el foco antessi el foco está dentrocoincide con :modalsínoaria-modal implícitotruefalsesolo el modal deja inerte la páginaclosedby="any" (clic fuera): Chrome/Edge 134+, Firefox 141+, Safari solo en Preview

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; }
  1. La caja del diálogo: ancho máximo de 28rem que nunca toca los bordes en un celular, relleno y borde. No le pongas display aquí: en nuestra prueba, dialog { display: flex; } dejó visible un diálogo cerrado, porque pisa el display: none del navegador. Si necesitas flex, usa dialog[open].
  2. El fondo que oscurece la página. Como el resto de la página está inerte, el ::backdrop solo es visual.
  3. 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>
  1. El <style> son las tres reglas de la sección anterior.
  2. El h1 tiene tabindex="-1" para poder recibir el foco desde el script sin entrar en el orden de Tab.
  3. Cada Quitar es type="button" y nombra su fila con data-item.
  4. El <dialog> lleva aria-labelledby="confirm-title": su nombre accesible es el texto del h2.
  5. 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 su value en returnValue.
  6. autofocus está en Cancelar, la opción segura: si el usuario pulsa Enter sin leer, no se borra nada.
  7. El listener del ul atiende a todos los botones con closest(".remove"), guarda la fila en pending, pone returnValue en vacío y abre con showModal().
  8. El reinicio de returnValue importa: 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.
  9. close llega siempre, se cierre como se cierre. Si la respuesta fue "remove", borra la fila.
  10. El navegador ya devolvió el foco a Quitar, pero ese botón se va con la fila. Sin el focus() al h1, el foco caería en body.

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>
  );
}
  1. "use client" marca el archivo como componente de cliente en Next.js; fuera de Next.js no hace nada.
  2. dialogRef apunta al <dialog>, y useId() genera un id único para el título, porque cada fila del carrito tiene su propio diálogo.
  3. open() reinicia returnValue y llama showModal(). No hay estado isOpen: el navegador ya sabe si está abierto.
  4. onClose es el evento close del navegador, que React expone para <dialog> según su documentación de componentes comunes. Ahí se lee returnValue.
  5. Cancelar va primero a propósito y no lleva autoFocus. React enfoca un autoFocus «al montar», cuando el diálogo todavía está cerrado, y en nuestra prueba con React 19.0.0 no escribió el atributo autofocus en el DOM; al abrir, el navegador enfocó el primer botón. Si necesitas otro control, llama su focus() después de showModal().
  6. Cart borra el producto y mueve el foco al h1, 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)
  1. Al abrir, el foco está en Cancelar, el de autofocus.
  2. Un clic sobre el Quitar del fondo cae en el <dialog>.
  3. Escape: cancel (cancelable) y luego close.
  4. El foco vuelve a Quitar, que lo tenía al llamar showModal().
  5. Quitar, dentro del diálogo, deja "remove" en returnValue.
  6. 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.

las partes de un modal hecho con <dialog>::backdrop¿Quitar este producto?<form method="dialog">CancelarQuitarvalue="cancel" · value="remove"dialog::backdropcubre la página, que queda inertearia-labelledby="confirm-title"el h2 le da nombre al dialog<form method="dialog">un botón lo cierra y fija returnValueautofocusrecibe el foco al abrirel navegador lo pone en la capa superiortú pones el nombre (aria-labelledby) y un botón visible para cerrar

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 cada showModal().
  • Confiar en autoFocus de React. Enfoca al montar, con el diálogo cerrado.
  • Poner display en el selector dialog. El diálogo cerrado se vuelve visible. Usa dialog[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 cada cancel deja 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 con show() ni con el atributo open.
  • El <dialog> tiene nombre: aria-labelledby al título visible o aria-label.
  • Hay un botón visible para cerrar, con texto o con aria-label.
  • autofocus está en el control que el usuario necesita primero; en una confirmación, la opción segura.
  • Los botones del formulario usan method="dialog" y un value distinto, y reinicias returnValue antes 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 ::backdrop y no se desplaza: html:has(dialog:modal) { overflow: hidden; }.
  • No hay tabindex en el <dialog> ni display en el selector dialog.
  • 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

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

Publicado el 3 de noviembre de 2026

← Blog