Mini-librería de modales, dropdowns y selects con animaciones ancladas al origen. El panel no aparece de la nada: nace del elemento que lo abrió y vuelve a él al cerrarse.
Un modal normal aparece con un fade o un scale desde el centro de la pantalla. Funciona, pero rompe la continuidad visual: el usuario hace clic en un botón acá y aparece un panel allá, sin relación espacial entre ambos.
wisspop mantiene esa relación. El panel arranca exactamente con el tamaño, la posición y el border-radius del botón que lo abrió, y crece hasta su forma final. Al cerrarse hace el camino inverso. El ojo sigue el objeto y no pierde el hilo.
Instala wisspop con tu gestor de paquetes preferido:
pnpm add wisspop # o npm install wisspop / yarn add wisspop Catálogo completo de demostraciones de wisspop con sus métodos, configuraciones de origen, animaciones viajeras y gestos.
El panel nace del botón y se posiciona en cualquiera de sus 6 combinaciones. El parámetro align controla la posición sobre el eje cruzado.
El radio del origen se lee dinámicamente del CSS. El glifo del botón '+' viaja hacia el elemento data-wisspop-title.
placement: 'origin' hace que el panel comparta el centro con el botón y se expanda directamente ahí sin viajar al centro de la ventana.
drawer-left, drawer-right, drawer-top y drawer-bottom adhieren el panel a los bordes completos de la ventana.
El texto del botón despegado viaja e interpola escala y posición hasta aterrizar en el título data-wisspop-title.
Se escala automáticamente texto con font-size o imágenes y nodos con width/height. Admite solo texto, texto con icono, solo icono o imágenes completas.
No hay nodo que medir, el punto de partida sale del texto del botón.
El icono medido en em escala exactamente junto con el texto.
Sin texto que escalar, el core pasa a modo box animando width/height.
Despega desde la miniatura y aterriza en el destino manteniendo proporción.
swipeToClose: true permite descartar el panel arrastrándolo hacia cualquier dirección con el mouse o dedo.
Hacia cualquier lado con el mouse o dedo. Si soltás antes del umbral, vuelve solo.
Elementos individuales con data-flip-id viajan del origen al modal conservando su identidad visual con GSAP Flip.
Clic para expandir detalle
Esta foto y título viajaron directamente desde la tarjeta usando GSAP Flip conservando dimensiones reales.
Despliegue elástico ligero con enterDropdownAnimation y leaveDropdownAnimation.
Demuestra resync() al modificar la altura del contenido dinámicamente y changeView() para alternar entre Login y Signup sin cerrar el panel.
Personaliza el fondo detrás del modal: activa los presets nativos overlayBlur y overlayDark, o aplica clases directas con overlayClass.
overlayBlur: true aplica backdrop-filter: blur(6px) sobre el fondo sin necesidad de escribir CSS.
overlayDark: true aplica un fondo oscuro sutil (rgba(0, 0, 0, 0.25)) para destacar el modal.
overlayBlur: true junto con overlayDark: true fusionan desenfoque y contraste óptico automáticamente.
overlayClass='bg-indigo-950/60 backdrop-blur-md' te da control total sobre colores, opacidad y niveles de desenfoque.
La instancia devuelta por createModal() o expuesta por los wrappers contiene los siguientes métodos de control:
| Método | Firma | Descripción |
|---|---|---|
| open | (originRef, label?, options?) | Inicia la animación de apertura despegando desde el origen medido. |
| close | () | Inicia la animación de cierre retornando a la posición actual del origen. |
| changeView | (mutateFn) | Aplica el cambio de vista y ajusta el alto con un fade-through corto sin cerrar el panel. |
| resync | () | Recalcula la geometría del contenido y ajusta suavemente la altura del panel abierto. |
| destroy | () | Limpia observers y elimina los elementos del DOM. |
Configura la posición (top, bottom, left, right, origin, center, drawer-left), alineación, gap, bloqueo de scroll y callbacks.
| Opción | Valores | Por defecto | Descripción |
|---|---|---|---|
| placement | top | bottom | left | right | origin | center | drawer-left | drawer-right | drawer-top | drawer-bottom | 'bottom' | Posición respecto al origen. origin crece en el lugar; drawer-* fija a bordes. |
| align | start | center | end | 'center' | Alineación sobre el eje cruzado al punto de anclaje. |
| gap | number (px) | 8 | Distancia en px hacia el elemento disparador. |
| margin | number (px) | 16 | Margen mínimo de seguridad a los bordes de la ventana. |
| swipeToClose | boolean | false | Permite descartar el panel arrastrándolo con la mano o mouse. |
| overlay | boolean | true | Renderiza una capa de telón de fondo (backdrop) detrás del modal. |
| overlayBlur | boolean | false | Aplica un desenfoque de fondo nativo (6px) con backdrop-filter sin CSS extra. |
| overlayDark | boolean | false | Aplica un fondo oscurecido suave predeterminado (rgba(0, 0, 0, 0.25)). |
| overlayClass | string | "" | Clases CSS o utilidades Tailwind para personalizar la opacidad, color y blur (ej. 'bg-black/60 backdrop-blur-md'). |
| overlayDuration | number | undefined | Duración en segundos de la animación del overlay (por defecto hereda duration). |
| closeOnEscape | boolean | true | Cierra el modal al pulsar la tecla Escape. |
| lockScroll | boolean | true | Bloquea el scroll del body con compensación de scrollbar. |
| fullscreenOnMobile | boolean | true | Modales grandes toman la pantalla completa en pantallas menores a 640px. |
El telón de fondo (overlay) de WissPop es completamente flexible. Puedes ajustar la opacidad del backgroundColor y la intensidad del backdrop-blur mediante 3 enfoques:
Pasa clases personalizadas o utilidades de Tailwind directamente al modal para controlar la opacidad exacta (ej. `bg-black/50` o `bg-slate-900/80`) y el desenfoque (`backdrop-blur-sm`, `backdrop-blur-md`, `backdrop-blur-xl`):
import { createModal } from 'wisspop/vanilla';
const modal = createModal({
overlay: true,
// 60% opacidad negra + desenfoque medio
overlayClass: 'bg-black/60 backdrop-blur-md',
content: '<div class="p-6">Contenido...</div>'
}); <template>
<WissPopMorph
v-model="isOpen"
:origin-ref="btnRef"
overlayClass="bg-black/60 backdrop-blur-md"
>
<div class="p-6">Contenido...</div>
</WissPopMorph>
</template> WissPop lee variables CSS estándar. Puedes sobreescribirlas a nivel global en tu `:root` o de forma aislada en una clase CSS:
/* Configuración global para toda tu aplicación */
:root {
/* Color y nivel de opacidad (ej. 40%, 50%, 75%) */
--wisspop-overlay-bg: rgba(0, 0, 0, 0.55);
/* Intensidad del desenfoque (ej. blur(4px), blur(12px), blur(20px)) */
--wisspop-overlay-blur: blur(10px);
}
/* O para un modal específico */
.overlay-vidrio-intenso {
--wisspop-overlay-bg: rgba(15, 23, 42, 0.8);
--wisspop-overlay-blur: blur(20px);
} Si no necesitas Tailwind ni CSS adicional, puedes activar los presets predefinidos con flags booleanos:
overlayBlur: true → Aplica desenfoque estándar de 6px (`backdrop-filter: blur(6px)`). overlayDark: true → Aplica un oscurecido sutil estándar (`rgba(0, 0, 0, 0.25)`). overlayBlur: true, overlayDark: true → Combina automáticamente ambos estilos sin necesidad de clases adicionales. createModal({
overlay: true,
overlayBlur: true, // Desenfoque nativo 6px
overlayDark: true, // Fondo oscuro suave
content: '<div class="p-6">Panel con blur nativo</div>'
}); <WissPopMorph
v-model="isOpen"
:origin-ref="btnRef"
:overlay="true"
:overlay-blur="true"
:overlay-dark="true"
>
<div class="p-6">Panel con blur nativo</div>
</WissPopMorph> Core sin dependencias (JS puro + GSAP) con adaptador nativo para Vue 3 y API agnóstica para Vanilla JS.
<script setup>
import { ref } from 'vue';
import { WissPopMorph } from 'wisspop/vue';
const open = ref(false);
const btnRef = ref(null);
</script>
<template>
<button ref="btnRef" @click="open = true">Abrir</button>
<WissPopMorph v-model="open" :origin-ref="btnRef" placement="bottom" modalClass="panel">
<template #default="{ close }">
<p>Contenido Vue...</p>
<button @click="close">Cerrar</button>
</template>
</WissPopMorph>
</template> import { createModal } from 'wisspop/vanilla';
const modal = createModal({
content: '<p>Contenido...</p>',
placement: 'bottom',
modalClass: 'panel',
closeButton: true,
});
document.querySelector('#btn').addEventListener('click', (e) => {
modal.open(e.currentTarget);
}); Astro no necesita wrapper reactivo. Usa la API vanilla directamente en una etiqueta <script> del componente .astro.
---
// MiModal.astro
---
<button id="mi-btn">Abrir modal</button>
<script>
import { createModal } from 'wisspop/vanilla';
const modal = createModal({
content: '<div class="p-6"><h2 data-wisspop-title>Hola Astro</h2><p>Contenido del modal</p></div>',
placement: 'bottom',
modalClass: 'panel',
closeButton: true,
});
document.getElementById('mi-btn')
?.addEventListener('click', (e) => modal.open(e.currentTarget));
</script> React aún no tiene wrapper nativo. Usa la API vanilla con useRef y useEffect para integrar wisspop.
import { useRef, useEffect } from 'react';
import { createModal } from 'wisspop/vanilla';
export default function MiModal() {
const btnRef = useRef(null);
const modalRef = useRef(null);
useEffect(() => {
modalRef.current = createModal({
content: '<div class="p-6"><h2 data-wisspop-title>Hola React</h2><p>Contenido</p></div>',
placement: 'bottom',
modalClass: 'panel',
closeButton: true,
});
return () => modalRef.current?.destroy?.();
}, []);
return (
<button ref={btnRef} onClick={() => modalRef.current?.open(btnRef.current)}>
Abrir modal
</button>
);
} WissPop incluye definiciones de tipos automáticas (.d.ts) para Vanilla, Vue 3 y Core. No necesitas instalar paquetes de tipos adicionales.
import { createModal, createFlipModal, setDefaults } from 'wisspop/vanilla';
// Todas las opciones, métodos y estados cuentan con autocompletado y tipado estricto
const modal = createModal({
content: '<div class="p-6"><h2>Modal Tipado</h2></div>',
placement: 'center',
duration: 0.6,
overlay: true,
overlayBlur: true,
swipeToClose: true,
});
const trigger = document.querySelector<HTMLButtonElement>('#mi-boton');
trigger?.addEventListener('click', () => {
modal.open(trigger);
}); Patrones recomendados, advertencias técnicas y soluciones aprendidas para integrar WissPop con la máxima fluidez visual.
| Componente | Tipo de Animación | Cuándo Usarlo | Elementos y Reglas |
|---|---|---|---|
| WissPopMorph | La caja física nace del botón y se expande/transforma hacia su
destino (placement="origin" o anclado). | Dropdowns, menús contextuales, drawers laterales, mini-modales de confirmación o aviso. | NO usa texto volador. La caja hace todo el morph físico. |
| WissPopPill | La caja se expande y el texto o icono del botón vuela e interpola su escala hacia el título. | Modales de formularios principales, login/auth, calculadoras donde la etiqueta del botón se convierte en el título. | Requiere [data-wisspop-title] en el modal y opcionalmente
data-wisspop-label en el botón. |
| WissPopFlip | Transición FLIP completa de múltiples elementos compartidos (imágenes, títulos, badges) entre tarjeta y vista de detalle. | Galerías de productos, cards interactivas que se expanden a pantalla completa. | Requiere atributos data-flip-id="id-unico" coincidentes
en el trigger y en el modal. |
El Problema: Wisspop anima directamente su propio elemento
contenedor .wisspop-box (modifica con GSAP width, height, borderRadius, top y left). Si dentro del slot colocas otro <div> con fondo,
borde, redondeo y sombra, habrá dos cajas compitiendo y se producirá un
salto o retraso visual ("efecto pop").
La Solución: Pasa los estilos del contenedor directamente
a la propiedad modalClass.
<WissPopMorph id="mi-modal" placement="origin">
<!-- Doble contenedor: compite con .wisspop-box -->
<div class="bg-white rounded-2xl border border-slate-900 shadow-xl p-5">
<h3>Contenido</h3>
</div>
</WissPopMorph> <WissPopMorph
id="mi-modal"
placement="origin"
modalClass="bg-white dark:bg-zinc-900 rounded-2xl border border-zinc-200 dark:border-zinc-800 shadow-xl"
closeButton={true}
swipeToClose={true}
>
<!-- Contenido interno limpio con ancho responsivo -->
<div class="p-5" style="width: min(24rem, calc(100vw - 2rem));">
<h3 class="font-bold text-base">Contenido</h3>
</div>
</WissPopMorph> El Problema: flyingTextClass y data-wisspop-title son exclusivos
del sistema de texto viajero de WissPopPill. Si los
usas en un WissPopMorph, Wisspop ocultará temporalmente
el título (visibility: hidden) esperando una animación de
vuelo que nunca ocurrirá.
La Solución: En WissPopMorph, usa
encabezados HTML normales <h3> sin data-wisspop-title. Para títulos con texto viajero, utiliza <WissPopPill>.
<!-- Ocultará el título esperando un vuelo que no ocurrirá -->
<WissPopMorph id="mi-modal" modalClass="panel">
<div class="p-5" style="width: min(24rem, calc(100vw - 2rem));">
<h3 data-wisspop-title>Título Oculto</h3>
</div>
</WissPopMorph> <!-- Encabezado normal sin atributos de vuelo -->
<WissPopMorph id="mi-modal" modalClass="panel">
<div class="p-5" style="width: min(24rem, calc(100vw - 2rem));">
<h3 class="font-bold text-lg">Título Visible</h3>
</div>
</WissPopMorph> El Problema: Para que GSAP mida con precisión la geometría final de la caja antes de animar el despegue, el cuerpo del panel debe tener un ancho medible.
La Solución: Establece un ancho explícito o responsivo
en el div interior (ej. style="width: min(24rem, calc(100vw - 2rem));" o clases Tailwind equivalentes como w-80 max-w-[calc(100vw-2rem)]).
<WissPopMorph id="mi-modal" modalClass="panel">
<!-- Sin ancho: GSAP no puede calcular la geometría exacta -->
<div class="p-5">
<h3>Contenido sin ancho</h3>
</div>
</WissPopMorph> <WissPopMorph id="mi-modal" modalClass="panel">
<!-- Ancho explícito y responsivo para medición fluida -->
<div class="p-5" style="width: min(24rem, calc(100vw - 2rem));">
<h3>Contenido</h3>
</div>
</WissPopMorph> El Problema: En Astro, los slots se emiten dentro de etiquetas
<template data-wisspop="...">. Si un botón que abre
un submodal se encuentra dentro del template de otro modal que aún no
se ha abierto, document.querySelectorAll() no lo encontrará
en la carga inicial.
La Solución: El runtime cliente de wisspop/astro incluye delegación global automática de eventos para [data-wisspop-trigger], montando bajo demanda cualquier submodal anidado o disparador
dinámico.
<!-- Disparador dentro de otro modal o generado dinámicamente -->
<button data-wisspop-trigger="sub-modal-confirmacion" class="demo-btn">
Abrir Confirmación
</button>
<!-- El runtime monta el template bajo demanda al hacer clic -->
<WissPopMorph id="sub-modal-confirmacion" placement="center" modalClass="panel">
<div class="p-5" style="width: min(20rem, calc(100vw - 2rem));">
<h4 class="font-bold mb-3">¿Deseas confirmar la acción?</h4>
<button data-wisspop-close class="demo-btn w-full">Aceptar</button>
</div>
</WissPopMorph> El Problema: WissPop lee automáticamente el color de fondo
computado del botón disparador (getComputedStyle(ref).backgroundColor) y lo interpola con GSAP hacia el color del modal al abrir, y de vuelta al color del botón al cerrar. Si el botón tiene un color muy saturado o semitransparente (ej. bg-amber-500/10), toda la caja del modal se teñirá de ese tono mientras se encoge.
La Solución: Mantén el fondo del botón disparador en un
tono armónico o neutro respecto al modal (ej. bg-white, bg-zinc-100 o tonos arena), y aplica los colores de acento/alerta en iconos, bordes
o badges internos.
<!-- El modal completo se teñirá de amarillo al cerrar -->
<button class="bg-amber-500/10 border border-amber-500" data-wisspop-trigger="mi-modal">
Aviso Importante
</button> <!-- Fondo neutro; color de acento en el icono -->
<button class="bg-zinc-100 dark:bg-zinc-800 border border-zinc-300 dark:border-zinc-700 flex items-center gap-2 p-2 rounded-xl" data-wisspop-trigger="mi-modal">
<span class="bg-amber-100 dark:bg-amber-950 text-amber-600 p-1 rounded-lg">!</span>
<span>Aviso Importante</span>
</button>
Para asegurar que Astro y Vite procesen correctamente los módulos de
WissPop en SSR y durante las transiciones de página de <ClientRouter />:
// astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({
vite: {
plugins: [tailwindcss()],
ssr: {
noExternal: ['wisspop']
}
},
}); Trampa de foco, tecla Escape, restauración de foco al cerrar, bloqueo de scroll del body, soporte para reduced-motion y roles ARIA automáticos.
prefers-reduced-motion, se salta la animación hacia la geometría final.