Popover API: Diálogos Flotantes Accesibles y Nativos
Aprende a implementar popovers accesibles y posicionados usando la API Popover nativa del navegador, sin dependencias externas.
TL;DR - Resumen rápido
- La Popover API permite crear elementos flotantes nativos sin librerías externas
- Usa el atributo popover='auto' o popover='manual' para declarar un elemento como popover
- Los métodos showPopover(), hidePopover() y togglePopover() controlan el estado del popover
- Los eventos beforetoggle y toggle permiten reaccionar a cambios de estado
- El navegador maneja automáticamente el posicionamiento, accesibilidad y focus management
Introducción
Los popovers son elementos de interfaz que se muestran sobre el contenido principal, como menús desplegables, tooltips, tooltips informativos o diálogos contextuales. Antes de la Popover API, implementar estos componentes requería librerías externas como Popper.js o código JavaScript complejo para manejar el posicionamiento, accesibilidad y gestión del estado.
La Popover API nativa del navegador resuelve estos problemas proporcionando una solución integrada que maneja automáticamente el posicionamiento, la accesibilidad, el focus management y la interacción con el teclado. Esto significa que puedes crear popovers robustos y accesibles con menos código y sin dependencias externas.
Soporte del navegador
La Popover API está disponible en Chrome/Edge 114+, Firefox 125+ y Safari 17+. Para navegadores más antiguos, considera usar polyfills o proporcionar una experiencia alternativa.
¿Qué es la Popover API?
La Popover API es una API nativa del navegador que permite declarar elementos HTML como popovers. Un popover es un elemento que se muestra sobre el contenido de la página y que puede ser cerrado por el usuario. La API proporciona atributos HTML, métodos JavaScript y eventos para controlar el comportamiento del popover.
La principal ventaja de usar la Popover API sobre implementaciones personalizadas es que el navegador maneja automáticamente aspectos complejos como el posicionamiento inteligente, la gestión del focus, la accesibilidad (ARIA attributes), la interacción con el teclado y la superposición z-index. Esto reduce significativamente la cantidad de código necesario y elimina bugs comunes.
- Posicionamiento automático inteligente que evita que el popover se salga de la pantalla
- Gestión automática del focus para accesibilidad
- Soporte nativo para navegación por teclado (Escape para cerrar)
- Atributos ARIA generados automáticamente
- Capa de superposición (top layer) que evita problemas de z-index
- Dos modos de comportamiento: auto y manual
El atributo popover
El atributo popover es el punto de entrada principal para usar la API. Puedes agregar este atributo a cualquier elemento HTML para convertirlo en un popover. El atributo puede tener dos valores: "auto" o "manual", que determinan cómo se cierra el popover.
Modo auto
El modo auto es el más común y proporciona una experiencia de usuario familiar. En este modo, el popover se cierra automáticamente cuando el usuario hace clic fuera del popover o presiona la tecla Escape. Es ideal para menús desplegables, tooltips y otros componentes que deben cerrarse cuando el usuario interactúa con otras partes de la página.
En este ejemplo, el elemento div con el atributo popover="auto" se convierte en un popover. El botón con el atributo popovertarget="mi-popover" actúa como el disparador que muestra u oculta el popover. El navegador maneja automáticamente el posicionamiento y el cierre al hacer clic fuera o presionar Escape.
Modo manual
El modo manual proporciona más control sobre cuándo se cierra el popover. En este modo, el popover no se cierra automáticamente al hacer clic fuera o presionar Escape. Debes cerrarlo explícitamente usando JavaScript o un botón de cierre. Es ideal para casos donde necesitas que el popover permanezca abierto mientras el usuario interactúa con otros elementos, como en un asistente paso a paso o un tutorial interactivo.
El modo manual requiere que implementes tu propia lógica de cierre, pero te da control total sobre el comportamiento del popover. En este ejemplo, el popover solo se cierra cuando el usuario hace clic en el botón de cierre dentro del popover.
Precaución con el modo manual
Cuando uses el modo manual, asegúrate de proporcionar siempre una forma clara y accesible de cerrar el popover. Los usuarios con discapacidades visuales o que navegan por teclado pueden tener dificultades si no hay un botón de cierre visible y accesible.
Métodos JavaScript de la API
La Popover API proporciona tres métodos principales para controlar el estado del popover mediante JavaScript: showPopover(), hidePopover() y togglePopover(). Estos métodos te permiten mostrar, ocultar o alternar el estado del popover programáticamente, lo que es útil cuando necesitas controlar el popover desde código JavaScript en lugar de usar el atributo popovertarget.
showPopover()
El método showPopover() muestra el popover. Si el popover ya está visible, este método no hace nada. El método lanza una excepción si el elemento no tiene el atributo popover. Es útil cuando necesitas mostrar el popover en respuesta a eventos personalizados o condiciones específicas.
Este ejemplo muestra cómo usar showPopover() para mostrar un popover cuando el usuario hace clic en un botón. El método es simple y directo, pero debes asegurarte de que el elemento tenga el atributo popover antes de llamarlo.
hidePopover()
El método hidePopover() oculta el popover. Si el popover ya está oculto, este método no hace nada. Al igual que showPopover(), lanza una excepción si el elemento no tiene el atributo popover. Es útil cuando necesitas cerrar el popover en respuesta a eventos específicos o condiciones personalizadas.
Este ejemplo muestra cómo usar hidePopover() para cerrar un popover cuando el usuario hace clic en un botón de cierre. El método es útil para implementar botones de cierre personalizados o lógica de cierre condicional.
togglePopover()
El método togglePopover() alterna el estado del popover: si está visible, lo oculta; si está oculto, lo muestra. Este método es conveniente cuando necesitas un comportamiento de alternancia simple, como un botón que muestra u oculta un menú. Al igual que los otros métodos, lanza una excepción si el elemento no tiene el atributo popover.
Este ejemplo muestra cómo usar togglePopover() para alternar el estado de un popover con un solo botón. El método simplifica el código al no necesitar verificar el estado actual del popover antes de llamarlo.
Verificar el estado del popover
Para verificar si un popover está visible u oculto, puedes usar la propiedad matches() con el pseudo-selector :popover-open. Esta propiedad devuelve true si el popover está visible y false si está oculto. Es útil cuando necesitas tomar decisiones basadas en el estado actual del popover.
Este ejemplo muestra cómo verificar el estado de un popover usando el pseudo-selector :popover-open. La propiedad es útil para implementar lógica condicional basada en el estado del popover, como cambiar el texto de un botón según si el popover está abierto o cerrado.
Eventos del Popover
La Popover API proporciona dos eventos principales que te permiten reaccionar a cambios en el estado del popover: beforetoggle y toggle. Estos eventos son útiles para ejecutar código cuando el popover se muestra u oculta, como animaciones, actualizaciones de estado o seguimiento de analíticas.
Evento beforetoggle
El evento beforetoggle se dispara antes de que el popover cambie de estado. Este evento es cancelable, lo que significa que puedes prevenir que el popover se muestre u oculta llamando a preventDefault() en el objeto del evento. Es útil para validar condiciones antes de mostrar el popover o para realizar acciones preparatorias.
Este ejemplo muestra cómo usar el evento beforetoggle para validar una condición antes de mostrar el popover. Si la condición no se cumple, el popover no se muestra. El evento también es útil para cargar contenido dinámico antes de mostrar el popover.
Carga diferida de contenido
Usa el evento beforetoggle para cargar contenido dinámico solo cuando el popover está a punto de mostrarse. Esto mejora el rendimiento al evitar cargar contenido que el usuario nunca verá.
Evento toggle
El evento toggle se dispara después de que el popover ha cambiado de estado. A diferencia de beforetoggle, este evento no es cancelable porque el cambio ya ha ocurrido. Es útil para ejecutar código después de que el popover se muestra u oculta, como animaciones, actualizaciones de estado o seguimiento de analíticas.
Este ejemplo muestra cómo usar el evento toggle para ejecutar código después de que el popover cambia de estado. El evento es útil para animaciones, actualizaciones de UI o seguimiento de eventos de usuario.
Posicionamiento y Estilos
La Popover API maneja automáticamente el posicionamiento del popover, pero puedes personalizar su apariencia y comportamiento usando CSS. Los popovers se renderizan en la "top layer" del navegador, lo que significa que siempre aparecen sobre otros elementos sin necesidad de manipular z-index.
Posicionamiento automático
Por defecto, el navegador posiciona el popover automáticamente usando el atributo popovertarget como punto de referencia. El navegador calcula la posición óptima para evitar que el popover se salga de la pantalla. Puedes usar el atributo popovertargetaction para especificar si el botón debe mostrar, ocultar o alternar el popover.
Este ejemplo muestra cómo usar el atributo popovertargetaction para especificar la acción del botón. El valor "show" muestra el popover, "hide" lo oculta y "toggle" alterna el estado. El navegador maneja automáticamente el posicionamiento relativo al botón.
Estilos CSS
Puedes personalizar la apariencia del popover usando CSS. Los popovers tienen estilos predeterminados, pero puedes sobrescribirlos para que coincidan con el diseño de tu aplicación. El pseudo-selector :popover-open te permite aplicar estilos específicos cuando el popover está visible.
Este ejemplo muestra cómo personalizar la apariencia del popover usando CSS. El pseudo-selector :popover-open te permite aplicar estilos específicos cuando el popover está visible, como animaciones de entrada y salida. La propiedad ::backdrop te permite estilizar el fondo oscurecido detrás del popover.
Animaciones de entrada y salida
Usa transiciones y animaciones CSS con el pseudo-selector :popover-open para crear animaciones suaves de entrada y salida. El navegador maneja automáticamente el timing de las animaciones para que se sincronicen con el estado del popover.
Accesibilidad
Una de las principales ventajas de la Popover API es que maneja automáticamente muchos aspectos de accesibilidad. El navegador genera automáticamente los atributos ARIA necesarios, gestiona el focus y proporciona navegación por teclado. Sin embargo, hay algunas consideraciones adicionales que debes tener en cuenta para asegurar que tu popover sea completamente accesible.
- El navegador genera automáticamente los atributos ARIA necesarios (role, aria-expanded, aria-controls)
- El focus se mueve automáticamente al popover cuando se muestra y regresa al elemento disparador cuando se cierra
- La tecla Escape cierra automáticamente el popover en modo auto
- El popover está en la top layer, lo que evita problemas de z-index y superposición
- Los lectores de pantalla anuncian automáticamente cuando el popover se muestra u oculta
- Debes proporcionar un botón de cierre visible y accesible, especialmente en modo manual
Este ejemplo muestra cómo crear un popover accesible con un botón de cierre explícito y atributos ARIA adicionales para mejorar la experiencia de usuarios con lectores de pantalla. El atributo aria-label proporciona una descripción clara del propósito del popover.
Prueba con lectores de pantalla
Aunque la Popover API maneja automáticamente muchos aspectos de accesibilidad, siempre debes probar tus popovers con lectores de pantalla y navegación por teclado para asegurar una experiencia accesible para todos los usuarios.
Resumen: Popover API
Conceptos principales:
- •La Popover API permite crear elementos flotantes nativos sin librerías externas
- •El atributo popover declara un elemento como popover con valores 'auto' o 'manual'
- •Los métodos showPopover(), hidePopover() y togglePopover() controlan el estado del popover
- •Los eventos beforetoggle y toggle permiten reaccionar a cambios de estado
- •El navegador maneja automáticamente posicionamiento, accesibilidad y focus management
Mejores prácticas:
- •Usa el modo auto para la mayoría de los casos, solo usa manual cuando necesites control específico
- •Proporciona siempre un botón de cierre visible y accesible, especialmente en modo manual
- •Usa el evento beforetoggle para cargar contenido dinámico solo cuando sea necesario
- •Personaliza la apariencia con CSS usando el pseudo-selector :popover-open
- •Prueba siempre con lectores de pantalla y navegación por teclado para asegurar accesibilidad