Primeros pasos
Instala Glaze y el motor de animación que uses:
pnpm add glazejs gsap
# Or choose Motion:
pnpm add glazejs motion
GSAP y Motion son dependencias entre pares opcionales. Glaze no incluye ninguno de los dos motores.
Inicializa una sola vez
Llama a glaze() cuando tus elementos ya estén en el DOM. Proporciona el motor y toda la configuración en una sola llamada:
import glaze from "glazejs"
import { gsap } from "gsap"
const root = document.querySelector("#app")
if (!root) throw new Error("Missing application root")
const animations = glaze({
lib: { gsap: { core: gsap } },
element: root,
breakpoints: { md: "(min-width: 768px)" },
defaults: { element: "duration-0.6" },
presets: { rise: "from:opacity-0|y-24" },
watch: { debounceTime: 200 },
})
<div id="app">
<div data-animate="preset-rise"></div>
<div data-animate="@md:preset-rise from:duration-1"></div>
</div>
Esto analiza el elemento raíz y crea sus animaciones. Si vuelves a llamar a glaze(), se crea otra instancia; no se añade configuración a una instancia existente.
El adaptador explícito API es equivalente para GSAP:
import glaze from "glazejs"
import { createGsapAdapter } from "glazejs/gsap"
import { gsap } from "gsap"
const animations = glaze({ adapter: createGsapAdapter(gsap) })
Para Motion, usa createMotionAdapter({ animate, stagger }) desde glazejs/motion. Consulta la guía de Motion para conocer la configuración y las funciones compatibles. Elige adapter o lib en una sola configuración.
Opciones
| Opción | Predeterminado | Propósito |
|---|---|---|
lib.gsap.core |
ninguno | Instancia GSAP para la configuración original API. |
adapter |
ninguno | Adaptador explícito de GSAP o Motion; alternativa a lib. |
element |
document |
Elemento raíz del DOM que se analiza y observa. |
dataAttribute |
"data-animate" |
Atributo que contiene las utilidades de animación. |
className |
ninguno | Prefijo de clase para la sintaxis de clases. |
breakpoints |
{ default: "(min-width: 1px)" } |
Consultas de medios con nombre. |
defaults.tl |
ninguno | Configuración predeterminada de la línea de tiempo. |
defaults.element |
ninguno | Propiedades de animación predeterminadas; prevalecen las utilidades del elemento. |
presets |
ninguno | Cadenas de animación reutilizables con nombre. |
watch |
false |
Observar cambios en el DOM; true usa un retraso de 500 ms, o bien pasa { debounceTime }. |
El modo de observación detecta la adición y eliminación de elementos secundarios, así como los cambios en los atributos de animación dentro del elemento raíz. En el modo de clases, también detecta los cambios en las clases. Una mutación relevante del DOM programa una reconstrucción con retraso. Los cambios en los estilos de animación en línea no provocan reconstrucciones.
Actualización y limpieza
Conserva la instancia devuelta para gestionar el ciclo de vida:
// Rescan after rendering new elements when watch is disabled.
animations.refresh()
// On component unmount or page teardown:
animations.destroy()
refresh() reconstruye usando la configuración original. destroy() detiene las animaciones, elimina los observadores y los detectores de consultas de medios, y restaura los estilos en línea originales. Se puede llamar varias veces sin problema. Una instancia destruida no se puede reiniciar con refresh(); cree una instancia nueva al volver a montar.
El valor devuelto también incluye timelines, breakpoints y state, ya resuelto. Cada entrada de la línea de tiempo registra la línea de tiempo del motor, el ID, la consulta de medios, el elemento raíz, la configuración y los elementos animados. Mantenga las llamadas de reproducción específicas del motor en código que sepa qué adaptador creó la instancia.
Las actualizaciones y las reconstrucciones adaptables pueden reemplazar los objetos nativos de la línea de tiempo. Para controlar la reproducción después de una reconstrucción, lea el valor actual de timelines[index].timeline en lugar de conservar una referencia anterior a la línea de tiempo nativa.
CDN
Los puntos de entrada públicos son módulos ES y también se pueden cargar desde un CDN de ESM:
import glaze from "https://esm.sh/glazejs"
import { gsap } from "https://esm.sh/gsap@3.15.0"
const animations = glaze({ lib: { gsap: { core: gsap } } })