GSAP
Contrato de HyperFrames
HyperFrames controla GSAP a través de su adaptador de tiempo de ejecución gsap. Crea una línea de tiempo en pausa de forma síncrona, regístrala en window.__timelines con el data-composition-id exacto, y deja que HyperFrames la busque.
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
tl.from(".title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.to(".accent", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.25);
window.__timelines["main"] = tl; // la clave debe ser igual a data-composition-id de la raíz de la composición
</script>
- La clave del registro debe coincidir con el
data-composition-idde la raíz de la composición. - No llames a
tl.play()para movimientos críticos de renderizado. - No construyas líneas de tiempo dentro de código asíncrono, temporizadores o manejadores de eventos.
- Mantén los bucles finitos. HyperFrames renderiza duraciones de video finitas.
Métodos de interpolación principales
- gsap.to(targets, vars) — anima desde el estado actual a
vars. El más común. - gsap.from(targets, vars) — anima desde
varsal estado actual (entradas). - gsap.fromTo(targets, fromVars, toVars) — inicio y fin explícitos.
- gsap.set(targets, vars) — aplica inmediatamente (duración 0).
Usa siempre nombres de propiedades en camelCase (ej. backgroundColor, rotationX).
Variables comunes
- duration — segundos (por defecto 0.5).
- delay — segundos antes del inicio.
- ease —
"power1.out"(por defecto),"power3.inOut","back.out(1.7)","elastic.out(1, 0.3)","none". - stagger — número
0.1u objeto:{ amount: 0.3, from: "center" },{ each: 0.1, from: "random" }. - overwrite —
false(por defecto),true, o"auto". - repeat — número finito; nunca
-1en HyperFrames. Calcula las repeticiones a partir de la duración visible. yoyo — alterna dirección con repetición. - onComplete, onStart, onUpdate — callbacks.
- immediateRender — por defecto
truepara from()/fromTo(). Ponlo enfalseen interpolaciones posteriores que apunten a la misma propiedad+elemento para evitar sobrescritura.
Transformaciones y CSS
Prefiere los alias de transformación de GSAP sobre la cadena transform cruda:
| Propiedad GSAP | Equivalente |
|---|---|
x, y, z | translateX/Y/Z (px) |
xPercent, yPercent | translateX/Y en % |
scale, scaleX, scaleY | scale |
rotation | rotate (deg) |
rotationX, rotationY | 3D rotate |
skewX, skewY | skew |
transformOrigin | transform-origin |
- autoAlpha — prefiérelo sobre
opacity. En 0: también establecevisibility: hidden. - Variables CSS —
"--hue": 180. - svgOrigin (solo SVG) — origen del espacio de coordenadas SVG global. No lo combines con
transformOrigin. - Rotación direccional —
"360_cw","-170_short","90_ccw". - clearProps —
"all"o separado por comas; elimina estilos en línea al completarse. - Valores relativos —
"+=20","-=10","*=2".
Valores basados en funciones
gsap.to(".item", {
x: (i, target, targets) => i * 50,
stagger: 0.1,
});
Easing
Easings incorporados: power1–power4, back, bounce, circ, elastic, expo, sine. Cada uno tiene .in, .out, .inOut.
Valores predeterminados
gsap.defaults({ duration: 0.6, ease: "power2.out" });
Control de interpolaciones
const tween = gsap.to(".box", { x: 100 });
tween.pause();
tween.play();
tween.reverse();
tween.kill();
tween.progress(0.5);
tween.time(0.2);
gsap.matchMedia() (Responsivo + Accesibilidad)
Ejecuta la configuración solo cuando una media query coincide; se revierte automáticamente cuando deja de coincidir.
let mm = gsap.matchMedia();
mm.add(
{
isDesktop: "(min-width: 800px)",
reduceMotion: "(prefers-reduced-motion: reduce)",
},
(context) => {
const { isDesktop, reduceMotion } = context.conditions;
gsap.to(".box", {
rotation: isDesktop ? 360 : 180,
duration: reduceMotion ? 0 : 2,
});
},
);
Líneas de tiempo
Crear una línea de tiempo
const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });
Parámetro de posición
El tercer argumento controla la ubicación:
- Absoluto:
1— a los 1s - Relativo:
"+=0.5"— después del final;"-=0.2"— antes del final - Etiqueta:
"intro","intro+=0.3" - Alineación:
"<"— mismo inicio que el anterior;">"— después de que termine el anterior;"<0.2"— 0.2s después de que comience el anterior
tl.to(".a", { x: 100 }, 0);
tl.to(".b", { y: 50 }, "<"); // mismo inicio que .a
tl.to(".c", { opacity: 0 }, "<0.2"); // 0.2s después de que comience .b
Etiquetas
tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.play("outro");
tl.tweenFromTo("intro", "outro");
Opciones de línea de tiempo
- paused: true — crea pausada; llama a
.play()para iniciar. - repeat, yoyo — aplica a toda la línea de tiempo.
- defaults — variables combinadas en cada interpolación hija.
Anidamiento de líneas de tiempo
const master = gsap.timeline();
const child = gsap.timeline();
child.to(".a", { x: 100 }).to(".b", { y: 50 });
master.add(child, 0);
Control de reproducción
tl.play(), tl.pause(), tl.reverse(), tl.restart(), tl.time(2), tl.progress(0.5), tl.kill().
Rendimiento
Prefiere transformación y opacidad
Animar x, y, scale, rotation, opacity se mantiene en el compositor. Evita width, height, top, left cuando las transformaciones logren el mismo efecto.
will-change
will-change: transform;
Solo en elementos que realmente se animen.
gsap.quickTo() para actualizaciones frecuentes
let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
yTo = gsap.quickTo("#id", "y", { duration: 0.4, ease: "power3" });
container.addEventListener("mousemove", (e) => {
xTo(e.pageX);
yTo(e.pageY);
});
Stagger sobre muchas interpolaciones
Usa stagger en lugar de interpolaciones separadas con retrasos manuales.
Limpieza
Pausa o elimina animaciones fuera de pantalla.
Referencias (cargadas bajo demanda)
- references/effects.md — Efectos listos para usar: texto de máquina de escribir, visualizador de audio. Léelo cuando necesites patrones de efectos ya preparados para HyperFrames.
Buenas prácticas
- Usa nombres de propiedades en camelCase; prefiere alias de transformación y autoAlpha.
- Prefiere líneas de tiempo sobre encadenamiento con delay; usa el parámetro de posición.
- Agrega etiquetas con
addLabel()para una secuencia legible. - Pasa valores predeterminados al constructor de la línea de tiempo.
- Guarda el valor de retorno de la interpolación/línea de tiempo al controlar la reproducción.
No hacer
- Animar propiedades de layout (width/height/top/left) cuando las transformaciones sean suficientes.
- Usar svgOrigin y transformOrigin en el mismo elemento SVG.
- Encadenar animaciones con delay cuando una línea de tiempo pueda secuenciarlas.
- Crear interpolaciones antes de que exista el DOM.
- Omitir la limpieza — siempre elimina las interpolaciones cuando ya no sean necesarias.
- Usar valores de repetición infinitos en composiciones de HyperFrames. Usa recuentos de repetición finitos calculados a partir de la duración visible.
Créditos y referencias
- Fuente del adaptador de HyperFrames:
packages/core/src/runtime/adapters/gsap.ts. - Documentación de GSAP: https://gsap.com/docs/v3/
- Comportamiento de pausa y búsqueda de línea de tiempo de GSAP: https://gsap.com/docs/v3/GSAP/Timeline/pause%28%29/