API Popover nativa

Qué es un popover

Un popover es una ventana flotante que aparece sobre el contenido normal de la página para mostrar información complementaria o acciones rápidas. Ejemplos comunes son los menús desplegables, tooltips enriquecidos, selectores de fecha, cajas de ayuda contextual o paneles de notificaciones.

A diferencia de un modal (construido con <dialog>), un popover no bloquea la página ni oscurece el fondo. Su función es aparecer, ofrecer información y desaparecer cuando el usuario hace clic fuera o pulsa Escape, sin interrumpir el flujo de trabajo.

Antes de la API Popover de HTML, implementar estos componentes requería manejar manualmente:

• 1 - Posicionamiento absoluto o fijo cerca de un elemento disparador.
• 2 - Listeners para cerrar el popover al hacer clic fuera.
• 3 - Gestión del teclado (Escape, foco que entra y sale).
• 4 - Stacking context y z-index para asegurar que aparece sobre otros elementos.

La API Popover ofrece todo esto de forma nativa, con solo dos atributos HTML.

Atributos básicos

Para convertir cualquier elemento en un popover basta con añadirle el atributo popover. Por defecto, el elemento se oculta hasta que alguien lo abre.

<div id="menu-usuario" popover>
    <button>Mi perfil</button>
    <button>Configuracion</button>
    <button>Cerrar sesion</button>
</div>

Para asociar un botón que lo abra, se usa el atributo popovertarget apuntando al id del popover. El navegador gestiona automáticamente la apertura y cierre al pulsar el botón:

<button popovertarget="menu-usuario">Abrir menu</button>

<div id="menu-usuario" popover>
    <button>Mi perfil</button>
    <button>Configuracion</button>
    <button>Cerrar sesion</button>
</div>

Con este código, sin una sola línea de JavaScript, tenemos un menú funcional que:

• 1 - Se abre al pulsar el botón.
• 2 - Se cierra al pulsar fuera.
• 3 - Se cierra al pulsar Escape.
• 4 - Gestiona el foco automáticamente.
• 5 - Aparece en una capa superior sin problemas de z-index.

Modos auto y manual

El atributo popover acepta dos valores que controlan el comportamiento de cierre:

• 1 - popover="auto" (el valor por defecto cuando se escribe solo popover): se cierra al hacer clic fuera o al pulsar Escape. Solo puede haber un popover auto abierto a la vez; abrir uno nuevo cierra los anteriores.
• 2 - popover="manual": no se cierra automáticamente. El desarrollador debe cerrarlo explícitamente con código. Varios popovers manual pueden coexistir.

<!-- Cierra al hacer clic fuera -->
<div popover="auto">Tooltip informativo</div>

<!-- Requiere cierre manual -->
<div popover="manual">Notificacion persistente</div>

El modo auto cubre el 90% de los casos de uso. El modo manual se reserva para notificaciones tipo toast, paneles de detalles que deben permanecer abiertos mientras el usuario interactúa con otras partes, o widgets flotantes personalizados.

Acciones en el botón

El atributo popovertarget admite opcionalmente popovertargetaction para especificar qué acción realizar. Los valores posibles son show, hide y toggle:

<button popovertarget="ayuda" popovertargetaction="show">Mostrar ayuda</button>
<button popovertarget="ayuda" popovertargetaction="hide">Ocultar ayuda</button>
<button popovertarget="ayuda" popovertargetaction="toggle">Alternar ayuda</button>

<div id="ayuda" popover>
    <p>Texto de ayuda contextual.</p>
</div>

El valor por defecto es toggle, que es el más útil y cubre el caso común de un botón que abre y cierra el mismo popover.

Si el popover necesita un botón interno de cierre, se usa el mismo atributo dentro del propio popover:

<div id="detalles" popover>
    <h3>Detalles del pedido</h3>
    <p>Informacion ampliada...</p>
    <button popovertarget="detalles" popovertargetaction="hide">Cerrar</button>
</div>

Estilizado y posicionamiento

Por defecto, los popovers aparecen centrados en la pantalla con un padding mínimo. Para que queden cerca del botón que los abrió, se utiliza la propiedad CSS position-anchor junto con anchor-name en el disparador. Esta técnica, llamada anchor positioning, permite un posicionamiento declarativo sin cálculos manuales:

#boton-menu {
    anchor-name: --menu-usuario;
}

#menu-usuario {
    position: absolute;
    position-anchor: --menu-usuario;
    top: anchor(bottom);
    left: anchor(left);
    margin: 0;
}

Con anchor-name, el botón se marca como ancla. El popover luego referencia esa ancla y usa la función anchor() para posicionarse respecto a sus bordes. Este patrón elimina el JavaScript que antes se necesitaba para seguir al elemento disparador.

Para estilos básicos, el pseudoelemento ::backdrop también está disponible en popovers auto, aunque es menos usado que en <dialog>:

[popover] {
    border: 1px solid #e5e7eb;
    border-radius: 8px;
    padding: 1rem;
    box-shadow: 0 10px 40px rgba(0, 0, 0, 0.1);
}

[popover]::backdrop {
    background: transparent;
}

Animación de apertura y cierre

Los popovers pueden animarse con transiciones CSS aprovechando @starting-style y transition-behavior: allow-discrete. La técnica es idéntica a la usada con <dialog>:

[popover] {
    opacity: 0;
    transform: translateY(-8px);
    transition: opacity 0.2s, transform 0.2s, display 0.2s allow-discrete;
}

[popover]:popover-open {
    opacity: 1;
    transform: translateY(0);
}

@starting-style {
    [popover]:popover-open {
        opacity: 0;
        transform: translateY(-8px);
    }
}

La pseudoclase :popover-open aplica cuando el popover está visible. Combinando esta pseudoclase con @starting-style conseguimos una animación fluida de aparición.

Control con JavaScript

Aunque la API Popover está pensada para funcionar sin JavaScript, también expone métodos para controlarla programáticamente. Cualquier elemento con atributo popover tiene métodos showPopover(), hidePopover() y togglePopover():

const popover = document.getElementById('menu-usuario');

popover.showPopover();
popover.hidePopover();
popover.togglePopover();

También dispara un evento toggle cuando cambia de estado, útil para reaccionar a la apertura o cierre:

popover.addEventListener('toggle', (e) => {
    if (e.newState === 'open') {
        console.log('Popover abierto');
    } else {
        console.log('Popover cerrado');
    }
});

Popover vs dialog

Aunque <dialog> y la API Popover pueden parecer similares, sus roles son distintos:

• 1 - <dialog> con showModal() bloquea la interacción con el resto de la página. Apropiado para modales de confirmación, formularios que exigen atención, errores críticos.
• 2 - Popover no bloquea la página. El usuario puede seguir interactuando con el resto si lo desea. Apropiado para menús, tooltips, notificaciones, selectores contextuales.

flowchart LR
    A[Necesidad de UI flotante] --> B{Bloquea el resto?}
    B -->|Si| C[dialog showModal]
    B -->|No| D[popover auto]
    D --> E[Menus desplegables]
    D --> F[Tooltips enriquecidos]
    D --> G[Paneles contextuales]
    C --> H[Confirmaciones]
    C --> I[Formularios criticos]

Un caso habitual que ilustra la diferencia: un botón "Eliminar" abre un dialog modal para confirmar la acción (la confirmación exige atención), mientras que el icono de notificaciones abre un popover con el listado (informativo, no obliga a responder).

Accesibilidad

La API Popover gestiona automáticamente el aspecto accesible más difícil: el cierre coherente con Escape y la gestión del foco. Sin embargo, es responsabilidad del desarrollador:

• 1 - Etiquetar semánticamente el contenido del popover. Si es un menú, usar <ul> y <li>; si es un formulario, usar <form> y labels.
• 2 - Añadir atributos ARIA apropiados si el contenido lo requiere. Por ejemplo, role="menu" y role="menuitem" en menús complejos.
• 3 - Asegurar el contraste del texto y los bordes para que sea legible.
• 4 - Comprobar el uso con teclado: Tab debe moverse entre elementos internos, Escape debe cerrarlo.

En modo auto, solo un popover está abierto a la vez: el navegador gestiona la pila de popovers automáticamente, cerrando unos cuando se abre otro. Esta coherencia evita superposiciones extrañas de menús.

La API Popover es un ejemplo claro de cómo la plataforma web está reduciendo la necesidad de frameworks y componentes externos para interacciones comunes. Combinada con <dialog>, con el anidamiento CSS y con el selector :has(), permite construir interfaces complejas usando mayoritariamente HTML y CSS, reservando el JavaScript solo para la lógica de negocio.