GSAP
Single-voice craft (do NOT parallelize)
Writing a GSAP animation is one coherent authoring act with a single motion sensibility — timing, easing, and choreography must come from one hand. Do NOT fan out to sub-agents or split a single composition across parallel workers (their easing/duration choices will clash and the motion DNA will feel incoherent). Author the whole tween/timeline yourself, in order.
Craft moves (apply in this order):
- Choreograph before coding. Name the beats (entrance → emphasis → exit), assign each a
duration+ease, and decide overlaps via the position parameter ("<",">","-=0.2") — not manualdelay. One timeline, readable top-to-bottom. - Stay on the compositor. Animate only
x/y/scale/rotation/autoAlpha; neverwidth/height/top/leftwhen a transform achieves the same look. Set shared rhythm once viagsap.defaults()or the timelinedefaults. - Respect motion accessibility. Wrap motion in
gsap.matchMedia()with aprefers-reduced-motion: reducebranch that dropsdurationto 0 — every shipped animation, no exception.
Worked example — accessible staggered entrance with a controllable timeline:
const tl = gsap.timeline({ paused: true, defaults: { ease: "power2.out", duration: 0.6 } });
gsap.matchMedia().add("(prefers-reduced-motion: reduce)", () => {
tl.from(".card", { autoAlpha: 0, y: 24, stagger: 0.08 });
return () => tl.set(".card", { autoAlpha: 1, y: 0 }); // reduced-motion: snap, no movement
});
tl.play();
Output contract
Return runnable GSAP code (tween or timeline) using camelCase props + transform aliases, with: every animated element accounted for, a single coherent easing/duration system, a matchMedia reduced-motion branch, and stored return values when playback is controlled. State which beats map to which lines.
Verify before done
- API is real — every method/property/ease used appears in this reference (or
references/effects.md); never invent a GSAP API. If unsure it exists, say so rather than guess (no-hallucination). - Compositor-safe — no layout properties animated where a transform suffices.
- Reduced-motion — a
prefers-reduced-motionpath exists and zeroes movement. - Cleanup — off-screen/disposed tweens are killed; tweens are not created before the DOM exists.
Core Tween Methods
- gsap.to(targets, vars) — animate from current state to
vars. Most common. - gsap.from(targets, vars) — animate from
varsto 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.1or object:{ amount: 0.3, from: "center" },{ each: 0.1, from: "random" }. - overwrite —
false(default),true, or"auto". - repeat — number or
-1for infinite. yoyo — alternates direction with repeat. - onComplete, onStart, onUpdate — callbacks.
- immediateRender — default
truefor from()/fromTo(). Setfalseon 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 setsvisibility: 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 — 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 controlling playback.
Do Not
- Animate layout properties (width/height/top/left) when transforms suffice.
- Use both svgOrigin and transformOrigin on the same SVG element.
- Chain animations with delay when a timeline can sequence them.
- Create tweens before the DOM exists.
- Skip cleanup — always kill tweens when no longer needed.