Web y desarrollo

Cómo crear diálogos modales accesibles con HTML, CSS y JavaScript

How to Create Accessible Modal Dialogs with HTML, CSS, and JavaScript

Construya diálogos modales accesibles utilizando el elemento dialogo nativo de HTML. Aprenda cómo abrir y cerrar ventanas emergentes, gestionar el enfoque del teclado, estilizar fondos traslúcidos y crear diálogos de confirmación sin una biblioteca JavaScript.

Un visitante hace clic en un botón de tu sitio web. Aparece una ventana emergente con un formulario, un mensaje de confirmación o información adicional.

Crear la ventana emergente visual es fácil. Hacer que funcione correctamente con un teclado, un lector de pantalla y un navegador móvil es otra cuestión.

Muchas implementaciones modales personalizadas dependen de grandes cantidades de JavaScript para gestionar el foco, bloquear la interacción con la página y manejar la tecla Escape.

El HTML moderno ofrece un enfoque más sencillo: el elemento nativo <dialog>.

Proporciona gran parte del comportamiento esperado de un diálogo modal directamente en el navegador. Puedes crear una ventana emergente funcional con una pequeña cantidad de HTML, CSS y JavaScript, sin instalar un framework o plugin.

En este tutorial, construiremos un modal reutilizable, le daremos estilo, añadiremos un diálogo de confirmación y exploraremos los detalles de accesibilidad que importan en sitios web reales.

1. ¿Qué diferencia a un diálogo modal de una ventana emergente regular?

Un diálogo modal requiere temporalmente que el visitante interactúe con una parte particular de la interfaz antes de volver a la página principal.

Ejemplos típicos incluyen:

  • Confirmar la eliminación de un elemento.
  • Mostrar un formulario de contacto.
  • Pedir confirmación antes de abandonar una página.
  • Mostrar información adicional del producto.
  • Editar una configuración de la aplicación.

Un modal correctamente implementado debe dejar claro su propósito, ofrecer una forma obvia de cerrarlo y gestionar el foco del teclado apropiadamente.

El elemento nativo <dialog> soporta tanto comportamiento modal como no modal.

Método Comportamiento
showModal() Abre un modal y hace el resto del documento inerte
show() Abre un diálogo no modal
close() Cierra el diálogo
method="dialog" Permite que un botón de formulario cierre el diálogo

El comportamiento modal incluye gestión de foco e interacción con teclado proporcionada por el navegador.

2. Crea tu primer modal HTML

Empecemos con un ejemplo simple: un botón que abre un diálogo que contiene un título, algo de texto y un botón de cerrar.

<button type="button" id="openDialog">
    View delivery information
</button>

<dialog id="deliveryDialog"
        aria-labelledby="deliveryTitle">

    <h2 id="deliveryTitle">
        Delivery information
    </h2>

    <p>
        Orders are prepared within two business days.
        You will receive a tracking link by email.
    </p>

    <form method="dialog">
        <button type="submit" autofocus>
            Close
        </button>
    </form>

</dialog>

<script>
const openButton = document.getElementById('openDialog');
const dialog = document.getElementById('deliveryDialog');

openButton.addEventListener('click', () => {
    dialog.showModal();
});
</script>

Eso es suficiente para crear un diálogo modal funcional.

Cuando el visitante hace clic en el botón, showModal() abre el diálogo por encima del contenido de la página.

El navegador maneja varios comportamientos importantes automáticamente:

  • El diálogo entra en la capa superior (top layer), por encima del contenido ordinario de la página.
  • El resto del documento se vuelve inerte.
  • El foco del teclado se mueve dentro del diálogo.
  • Presionar Escape normalmente lo cierra.
  • El foco normalmente vuelve al botón de apertura cuando el diálogo se cierra.

El botón de cerrar usa method="dialog", así que no requiere un manejador de eventos JavaScript.

3. Da estilo al diálogo con CSS

El diálogo por defecto funciona, pero su apariencia es básica.

Podemos darle esquinas redondeadas, espaciado cómodo, ancho responsivo y un fondo (backdrop).

dialog {
    width: min(90vw, 520px);
    max-height: 85vh;
    box-sizing: border-box;
    padding: 2rem;
    border: 0;
    border-radius: 14px;
    background: #fff;
    color: #20242b;
    box-shadow: 0 20px 70px rgba(0, 0, 0, .2);
    overflow: auto;
}

dialog::backdrop {
    background: rgba(15, 23, 42, .65);
    backdrop-filter: blur(3px);
}

dialog h2 {
    margin-top: 0;
    font-size: 1.5rem;
}

dialog p {
    line-height: 1.6;
}

dialog button {
    padding: .75rem 1.25rem;
    border: 0;
    border-radius: 8px;
    background: #2458d3;
    color: #fff;
    font: inherit;
    cursor: pointer;
}

dialog button:focus-visible {
    outline: 3px solid #f59e0b;
    outline-offset: 3px;
}

El pseudo-elemento ::backdrop da estilo a la capa detrás de un diálogo modal.

Solo aparece cuando el diálogo se muestra modalmente, como a través de showModal().

Un diálogo abierto con show() no recibe automáticamente el mismo comportamiento de fondo modal.

¿Por qué usar la capa superior (top layer)?

Las ventanas emergentes personalizadas tradicionales a menudo dependen de valores z-index cada vez más grandes.

Un diálogo modal abierto con showModal() entra en la capa superior del navegador, lo que evita muchos problemas de contexto de apilamiento (stacking context).

Esto es particularmente útil en sitios web que contienen cabeceras fijas (sticky headers), widgets flotantes y constructores de páginas complejos.

4. Entiende la accesibilidad por teclado

Un modal debe funcionar sin ratón.

Imagina un visitante navegando tu sitio web usando la tecla Tab. Cuando se abre un modal, debería poder interactuar con sus controles sin moverse accidentalmente a la página detrás de él.

El diálogo modal nativo ayuda con este comportamiento.

El W3C describe el elemento HTML dialog como una técnica para crear diálogos modales accesibles, incluyendo contención de foco y retorno de foco cuando el diálogo se cierra.

Da al diálogo un nombre accesible

Usa un encabezado visible y reférencialo con aria-labelledby:

<dialog aria-labelledby="settingsTitle">
    <h2 id="settingsTitle">Account settings</h2>
    ...
</dialog>

Esto da a las tecnologías de asistencia un nombre significativo para el diálogo.

Elige el foco inicial cuidadosamente

El atributo autofocus puede identificar el control que debe recibir el foco cuando se abre el modal.

Para un diálogo informativo, enfocar el botón de cerrar puede ser apropiado.

Illustration of the article's main concept

Para un formulario, enfocar la primera entrada puede tener más sentido.

Para una confirmación destructiva, enfocar la acción más segura, como Cancelar, es a menudo preferible.

Evita colocar tabindex directamente en el elemento <dialog>; la especificación HTML prohíbe ese atributo en el elemento mismo.

Proporciona siempre un botón de cerrar visible

Aunque Escape normalmente cierra un diálogo modal, un control de cerrar visible sigue siendo esencial.

Los visitantes móviles pueden no tener un teclado físico, y algunos usuarios no sabrán que Escape puede descartar una ventana emergente.

5. Crea un diálogo de confirmación con dos botones

Ahora construyamos un ejemplo más útil: confirmar la eliminación de un elemento guardado.

El visitante debería poder elegir Cancelar o Eliminar.

HTML proporciona un mecanismo conveniente a través de method="dialog" y la propiedad returnValue del diálogo.

<button type="button" id="deleteItem">
    Delete item
</button>

<dialog id="confirmDialog"
        aria-labelledby="confirmTitle">

    <h2 id="confirmTitle">
        Delete this item?
    </h2>

    <p>
        This action cannot be undone.
    </p>

    <form method="dialog">
        <button value="cancel" autofocus>
            Cancel
        </button>

        <button value="confirm">
            Delete
        </button>
    </form>

</dialog>

<script>
const deleteButton = document.getElementById('deleteItem');
const confirmDialog = document.getElementById('confirmDialog');

deleteButton.addEventListener('click', () => {
    confirmDialog.returnValue = 'cancel';
    confirmDialog.showModal();
});

confirmDialog.addEventListener('close', () => {
    if (confirmDialog.returnValue === 'confirm') {
        // Call your application deletion logic here.
        console.log('Deletion confirmed');
    }
});
</script>

El detalle importante es que hacer clic en un botón dentro de un formulario method="dialog" cierra el diálogo y establece su returnValue.

Nuestro código verifica si el usuario seleccionó confirm.

Restablecer el valor antes de abrir previene que una confirmación anterior sea confundida con una nueva si el usuario descarta el diálogo con Escape.

El ejemplo intencionalmente no elimina nada. En una aplicación real, la acción confirmada llamaría a tu propio endpoint PHP o controlador de aplicación, con las protecciones de autorización y CSRF necesarias.

6. Prueba el flujo de confirmación

Una demostración útil es una lista de elementos guardados, cada uno con un botón Eliminar. Hacer clic en Eliminar debería abrir un diálogo de confirmación. Cancelar debería dejar el elemento intacto; Confirmar debería eliminar solo el elemento seleccionado.

Esto ilustra el flujo de confirmación sin cambiar datos reales del sitio web.

7. Añade un formulario de contacto dentro de un diálogo

Un formulario de contacto es otro caso de uso común.

Pero hay una diferencia importante entre cerrar un diálogo y enviar datos a un servidor.

Un formulario con method="dialog" cierra la ventana emergente. No envía una petición HTTP convencional a tu backend PHP.

Para un formulario de contacto real, usa un envío de formulario normal o una petición AJAX.

Por ejemplo:

<dialog id="contactDialog"
        aria-labelledby="contactTitle">

    <h2 id="contactTitle">
        Contact us
    </h2>

    <form action="/contact-handler.php" method="post">
        <label for="contactEmail">
            Your email
        </label>

        <input
            type="email"
            id="contactEmail"
            name="email"
            required
            autocomplete="email"
            autofocus
        >

        <label for="contactMessage">
            Your message
        </label>

        <textarea
            id="contactMessage"
            name="message"
            required
        ></textarea>

        <button type="submit">
            Send message
        </button>

        <button type="button" id="closeContact">
            Cancel
        </button>
    </form>
</dialog>

El botón Enviar envía el formulario normalmente.

El botón Cancelar debería cerrar el diálogo sin enviar:

document.getElementById('closeContact')
    .addEventListener('click', () => {
        document.getElementById('contactDialog').close();
    });

Tu manejador PHP sigue necesitando validar los datos enviados, implementar protección anti-spam y devolver una respuesta de éxito o error significativa.

Un diálogo modal mejora la interfaz; no reemplaza la seguridad del formulario en el servidor.

8. ¿Pueden los usuarios cerrar el diálogo haciendo clic fuera?

Muchos sitios web permiten a los visitantes descartar una ventana emergente haciendo clic en su fondo (backdrop).

Este comportamiento a menudo se llama light dismiss (descarte ligero).

El HTML moderno incluye el atributo closedby, que puede especificar si un diálogo puede ser descartado mediante interacción externa, solicitudes de cierre de la plataforma o controles explícitos.

Por ejemplo:

<dialog id="infoDialog" closedby="any">
    <h2>More information</h2>
    <p>Additional details appear here.</p>

    <form method="dialog">
        <button>Close</button>
    </form>
</dialog>

El valor closedby="any" permite el comportamiento de light-dismiss en navegadores que lo soportan.

Sin embargo, el soporte para características más nuevas de dialog debería verificarse contra tus navegadores objetivo. Las APIs básicas showModal() y close() están más ampliamente establecidas.

Para diálogos de confirmación críticos, el descarte accidental externo puede ser indeseable.

En todos los casos, mantén un control de cerrar o cancelar visible.

9. Evita estos errores comunes de implementación

Technical workflow illustration

Abrir un modal añadiendo el atributo open

Este código:

dialog.setAttribute('open', '');

no proporciona el mismo comportamiento que:

dialog.showModal();

El atributo open muestra el diálogo no modalmente. No hace automáticamente el resto del documento inerte.

Usa showModal() cuando necesites un modal real.

Eliminar el atributo open para cerrar un modal

Evita eliminar manualmente el atributo open de un modal activo.

Usa:

dialog.close();

Esto sigue el ciclo de vida previsto y asegura el comportamiento de cierre apropiado.

Usar un enlace en lugar de un botón

Un control que abre una acción de interfaz debería ser generalmente un botón:

<button type="button">Open settings</button>

Usa enlaces para navegación a otro recurso.

Olvidar la visibilidad del foco

Los usuarios que navegan con teclado necesitan una indicación visible de qué control está activo.

Mantén un estilo :focus-visible claro en lugar de eliminar los contornos de foco del navegador sin reemplazo.

Colocar el diálogo dentro de un contenedor oculto

Si un contenedor padre está oculto, o si un CMS reemplaza dinámicamente el marcado circundante, el diálogo puede comportarse inesperadamente.

Para integraciones con constructores de páginas, prefiere un contenedor estable y asegúrate de que el JavaScript se ejecute después de que el diálogo haya sido insertado en el documento.

10. Integra un diálogo en WordPress o Joomla

No necesitas crear una extensión solo para usar el elemento dialog nativo.

Para un sitio web simple, la integración consiste en tres partes:

Parte Dónde va
Marcado HTML Bloque HTML personalizado, módulo, plantilla o elemento de page-builder
CSS CSS personalizado del tema o plantilla
JavaScript Área de scripts soportada por el tema/plantilla, tema hijo, o extensión reputada de inserción de código que maneje JavaScript correctamente

WordPress

En WordPress, puedes colocar el HTML en un bloque HTML personalizado, siempre que tu cuenta y configuración del editor permitan el marcado necesario.

Añade el estilo a través del mecanismo de CSS personalizado soportado por tu tema.

Para el JavaScript, usa un área de scripts soportada por el tema, un tema hijo, o una extensión reputada de inserción de código que maneje JavaScript correctamente.

Algunos editores y configuraciones de seguridad filtran elementos <script>. Evita asumir que JavaScript pegado directamente en un bloque de contenido se ejecutará.

Joomla

En Joomla, un módulo personalizado o un editor que permita marcado HTML adecuado puede contener el diálogo.

Añade el CSS a la hoja de estilos personalizada de tu plantilla, como user.css en un sitio basado en Cassiopeia.

Coloca JavaScript en la ubicación de script personalizado soportada por la plantilla o a través de una extensión adecuada.

Dependiendo del editor configurado y filtros de texto, Joomla puede eliminar ciertos elementos o atributos cuando se guarda el contenido.

Si tu marcado desaparece, inspecciona la configuración del editor y filtrado en lugar de pegar repetidamente el mismo código.

Constructores de páginas (Page builders)

El mismo principio aplica a los constructores de páginas visuales: usa sus capacidades de integración HTML, CSS y JavaScript.

Para contenido cargado dinámicamente, inicializa los escuchadores de eventos solo después de que los elementos relevantes existan.

Si una página contiene múltiples diálogos, da a cada uno un ID único.

11. Prueba tu modal antes de publicar

Un diálogo que se ve correcto en escritorio puede seguir teniendo problemas de usabilidad.

Prúebalo con ratón, teclado y dispositivo móvil.

Prueba Resultado esperado
Hacer clic en botón de apertura El diálogo aparece
Presionar Tab El foco se mantiene dentro de los controles del modal
Presionar Shift + Tab La navegación inversa por teclado funciona
Presionar Escape El diálogo se cierra cuando está permitido
Hacer clic en Cerrar o Cancelar El diálogo se cierra
Cerrar el diálogo El foco vuelve apropiadamente
Abrir en móvil El contenido permanece legible y desplazable
Enviar formulario inválido La retroalimentación de validación es visible
Enviar formulario válido La aplicación maneja los datos correctamente
Usar un lector de pantalla El diálogo tiene un nombre comprensible

La técnica WCAG H102 del W3C proporciona orientación útil para validar el comportamiento modal nativo.

12. ¿Cuándo deberías usar un dialog en lugar de un plugin?

Un diálogo nativo es particularmente adecuado para interacciones pequeñas y enfocadas: confirmaciones, paneles informativos y formularios simples.

Para necesidades más complejas, como asistentes multi-paso, galerías avanzadas, o diálogos profundamente integrados con un flujo de trabajo de CMS, un componente o extensión dedicada puede seguir siendo la opción más mantenible.

La ventaja del enfoque nativo es que proporciona una base sólida soportada por el navegador sin introducir otra dependencia JavaScript.

También reduce la cantidad de gestión personalizada de foco y teclado que necesitas implementar tú mismo.

Conclusión: empieza con las capacidades integradas del navegador

Un diálogo modal no tiene que requerir una gran biblioteca JavaScript.

El elemento HTML <dialog> nativo proporciona una base efectiva para ventanas emergentes accesibles, mensajes de confirmación y formularios.

Con showModal(), close(), method="dialog" y unas pocas reglas CSS, puedes crear una interfaz que funcione en navegadores modernos mientras te beneficias del comportamiento integrado de foco y teclado.

Para WordPress, Joomla y sitios web PHP personalizados, esto puede ser una alternativa eficiente a instalar otro plugin para una interacción relativamente simple.

La clave es usar el comportamiento nativo correctamente, proporcionar controles claros y probar el resultado con interacciones reales de teclado y móvil.

Referencias oficiales y técnicas