/gsap

name: gsap
description: GSAP animation reference for HyperFrames. Covers gsap.to(), from(), fromTo(), easing, stagger, defaults, timelines (gsap.timeline(), position parameter, labels, nesting, playback), and performance (transforms, will-change, quickTo). Use when writing GSAP animations in HyperFrames compositions.

GSAP

Core Tween Methods

• **gsap.to(targets, vars)** — animate from current state to `vars`. Most common.
• **gsap.from(targets, vars)** — animate from `vars` to current state (entrances).
• **gsap.fromTo(targets, fromVars, toVars)** — explicit start and end.
• **gsap.set(targets, vars)** — apply immediately (duration 0).

Always use **camelCase** property names (e.g. `backgroundColor`, `rotationX`).

Common vars

• **duration** — seconds (default 0.5).
• **delay** — seconds before start.
• **ease** — `"power1.out"` (default), `"power3.inOut"`, `"back.out(1.7)"`, `"elastic.out(1, 0.3)"`, `"none"`.
• **stagger** — number `0.1` or object: `{ amount: 0.3, from: "center" }`, `{ each: 0.1, from: "random" }`.
• **overwrite** — `false` (default), `true`, or `"auto"`.
• **repeat** — number or `-1` for infinite. **yoyo** — alternates direction with repeat.
• **onComplete**, **onStart**, **onUpdate** — callbacks.
• **immediateRender** — default `true` for from()/fromTo(). Set `false` on later tweens targeting the same property+element to avoid overwrite.

Transforms and CSS

Prefer GSAP's **transform aliases** over raw `transform` string:

| GSAP property | Equivalent | | --------------------------- | ------------------- | | `x`, `y`, `z` | translateX/Y/Z (px) | | `xPercent`, `yPercent` | translateX/Y in % | | `scale`, `scaleX`, `scaleY` | scale | | `rotation` | rotate (deg) | | `rotationX`, `rotationY` | 3D rotate | | `skewX`, `skewY` | skew | | `transformOrigin` | transform-origin |

• **autoAlpha** — prefer over `opacity`. At 0: also sets `visibility: hidden`.
• **CSS variables** — `"--hue": 180`.
• **svgOrigin** _(SVG only)_ — global SVG coordinate space origin. Don't combine with `transformOrigin`.
• **Directional rotation** — `"360_cw"`, `"-170_short"`, `"90_ccw"`.
• **clearProps** — `"all"` or comma-separated; removes inline styles on complete.
• **Relative values** — `"+=20"`, `"-=10"`, `"*=2"`.

Function-Based Values

gsap.to(".item", {
  x: (i, target, targets) => i * 50,
  stagger: 0.1,
});

Easing

Built-in eases: `power1`–`power4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine`. Each has `.in`, `.out`, `.inOut`.

Defaults

gsap.defaults({ duration: 0.6, ease: "power2.out" });

Controlling Tweens

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() (Responsive + Accessibility)

Runs setup only when a media query matches; auto-reverts when it stops matching.

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,
    });
  },
);

---

Timelines

Creating a Timeline

const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });

Position Parameter

Third argument controls placement:

• **Absolute**: `1` — at 1s
• **Relative**: `"+=0.5"` — after end; `"-=0.2"` — before end
• **Label**: `"intro"`, `"intro+=0.3"`
• **Alignment**: `"<"` — same start as previous; `">"` — after previous ends; `"<0.2"` — 0.2s after previous starts

tl.to(".a", { x: 100 }, 0);
tl.to(".b", { y: 50 }, "<"); // same start as .a
tl.to(".c", { opacity: 0 }, "<0.2"); // 0.2s after .b starts

Labels

tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.play("outro");
tl.tweenFromTo("intro", "outro");

Timeline Options

• **paused: true** — create paused; call `.play()` to start.
• **repeat**, **yoyo** — apply to whole timeline.
• **defaults** — vars merged into every child tween.

Nesting Timelines

const master = gsap.timeline();
const child = gsap.timeline();
child.to(".a", { x: 100 }).to(".b", { y: 50 });
master.add(child, 0);

Playback Control

`tl.play()`, `tl.pause()`, `tl.reverse()`, `tl.restart()`, `tl.time(2)`, `tl.progress(0.5)`, `tl.kill()`.

---

Performance

Prefer Transform and Opacity

Animating `x`, `y`, `scale`, `rotation`, `opacity` stays on the compositor. Avoid `width`, `height`, `top`, `left` when transforms achieve the same effect.

will-change

will-change: transform;

Only on elements that actually animate.

gsap.quickTo() for Frequent Updates

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 > Many Tweens

Use `stagger` instead of separate tweens with manual delays.

Cleanup

Pause or kill off-screen animations.

---

References (loaded on demand)

• **[references/effects.md](references/effects.md)** — Drop-in effects: typewriter text, audio visualizer. Read when needing ready-made effect patterns for HyperFrames.

Best Practices

• Use camelCase property names; prefer transform aliases and autoAlpha.
• Prefer timelines over chaining with delay; use the position parameter.
• Add labels with `addLabel()` for readable sequencing.
• Pass defaults into timeline constructor.
• Store tween/timeline return value when controllin