GSAP (GreenSock) — Web Animation Skill
When to use
- High-quality UI/motion design: entrances, micro-interactions, page transitions
- Timeline-based sequences (vs. scattered CSS transitions)
- Scroll-driven storytelling (with ScrollTrigger)
- Complex easing, staggering, orchestration across many elements
Key concepts & APIs
- Tweens:
gsap.to(targets, vars)
gsap.from(targets, vars)
gsap.fromTo(targets, fromVars, toVars)
- Timelines:
const tl = gsap.timeline({ defaults, repeat, yoyo, paused })
- Chain:
tl.to(...).from(...).addLabel('x').add(() => ...)
- Position parameter: absolute
1.2, relative "+=0.5", overlap "-=0.3", label "intro"
- Eases:
ease: "power2.out", "expo.inOut", "elastic.out(1, 0.3)"
- Staggers:
stagger: 0.05 or { each, from: "start|center|end|random", grid }
- Performance-friendly properties:
- Prefer transforms (
x, y, scale, rotation) and opacity (autoAlpha)
- ScrollTrigger (plugin):
gsap.registerPlugin(ScrollTrigger)
- Inline:
gsap.to(".box", { scrollTrigger: ".box", x: 500 })
- Advanced:
scrollTrigger: { trigger, start, end, scrub, pin, snap, markers }
- Standalone:
ScrollTrigger.create({ trigger, start, end, onUpdate, onToggle })
Common pitfalls (and fixes)
- Animating layout properties (top/left/width/height) → jank
- Use transforms, add
will-change: transform, avoid forced reflow.
- ScrollTrigger “not firing” due to wrong trigger sizing/overflow containers
- Ensure trigger exists, has height, and check scroll container (nested scrolling needs config).
- Not cleaning up in SPA/React
- Use
gsap.context() and revert on unmount; kill triggers (ScrollTrigger.getAll().forEach(t => t.kill())) if needed.
- FOUC / measuring before fonts/images load
- Initialize after layout is stable; run
ScrollTrigger.refresh() after images load.
Quick recipes
1) Hero entrance (stagger)
gsap.from(".hero [data-anim]", {
y: 24,
autoAlpha: 0,
duration: 0.8,
ease: "power2.out",
stagger: 0.06,
});
2) Sequenced timeline
const tl = gsap.timeline({ defaults: { ease: "power2.out", duration: 0.6 } });
tl.from(".nav", { y: -20, autoAlpha: 0 })
.from(".hero-title", { y: 30, autoAlpha: 0 }, "-=0.2")
.from(".hero-cta", { scale: 0.95, autoAlpha: 0 }, "-=0.2");
3) Scroll-scrub pinned section
gsap.registerPlugin(ScrollTrigger);
gsap.timeline({
scrollTrigger: {
trigger: ".story",
start: "top top",
end: "+=800",
scrub: 1,
pin: true,
},
}).to(".story .panel", { xPercent: -200 });
What to ask the user (if requirements unclear)
- Is this a static site or SPA (React/Next/Vue)? Any page transitions?
- Do we need scroll-driven sections (pin/scrub/snap)?
- Performance constraints (mobile support, reduced motion)?
1---
2name: gsap
3description: Use when you need to add or debug professional web animations with GSAP (timelines, ScrollTrigger, stagger, transforms) in HTML/CSS/JS/React. Includes patterns for smooth motion, performance, and common pitfalls.
4metadata:
5 source: https://skillmd.com/skills/gabrielmoreira/gsap
6---
7
8# GSAP (GreenSock) — Web Animation Skill
9
10## When to use
11- High-quality UI/motion design: entrances, micro-interactions, page transitions
12- Timeline-based sequences (vs. scattered CSS transitions)
13- Scroll-driven storytelling (with ScrollTrigger)
14- Complex easing, staggering, orchestration across many elements
15
16## Key concepts & APIs
17- Tweens:
18 - `gsap.to(targets, vars)`
19 - `gsap.from(targets, vars)`
20 - `gsap.fromTo(targets, fromVars, toVars)`
21- Timelines:
22 - `const tl = gsap.timeline({ defaults, repeat, yoyo, paused })`
23 - Chain: `tl.to(...).from(...).addLabel('x').add(() => ...)`
24 - Position parameter: absolute `1.2`, relative `"+=0.5"`, overlap `"-=0.3"`, label `"intro"`
25- Eases: `ease: "power2.out"`, `"expo.inOut"`, `"elastic.out(1, 0.3)"`
26- Staggers: `stagger: 0.05` or `{ each, from: "start|center|end|random", grid }`
27- Performance-friendly properties:
28 - Prefer transforms (`x`, `y`, `scale`, `rotation`) and opacity (`autoAlpha`)
29- ScrollTrigger (plugin):
30 - `gsap.registerPlugin(ScrollTrigger)`
31 - Inline: `gsap.to(".box", { scrollTrigger: ".box", x: 500 })`
32 - Advanced: `scrollTrigger: { trigger, start, end, scrub, pin, snap, markers }`
33 - Standalone: `ScrollTrigger.create({ trigger, start, end, onUpdate, onToggle })`
34
35## Common pitfalls (and fixes)
36- Animating layout properties (top/left/width/height) → jank
37 - Use transforms, add `will-change: transform`, avoid forced reflow.
38- ScrollTrigger “not firing” due to wrong trigger sizing/overflow containers
39 - Ensure trigger exists, has height, and check scroll container (nested scrolling needs config).
40- Not cleaning up in SPA/React
41 - Use `gsap.context()` and revert on unmount; kill triggers (`ScrollTrigger.getAll().forEach(t => t.kill())`) if needed.
42- FOUC / measuring before fonts/images load
43 - Initialize after layout is stable; run `ScrollTrigger.refresh()` after images load.
44
45## Quick recipes
46
47### 1) Hero entrance (stagger)
48```js
49gsap.from(".hero [data-anim]", {
50 y: 24,
51 autoAlpha: 0,
52 duration: 0.8,
53 ease: "power2.out",
54 stagger: 0.06,
55});
56```
57
58### 2) Sequenced timeline
59```js
60const tl = gsap.timeline({ defaults: { ease: "power2.out", duration: 0.6 } });
61tl.from(".nav", { y: -20, autoAlpha: 0 })
62 .from(".hero-title", { y: 30, autoAlpha: 0 }, "-=0.2")
63 .from(".hero-cta", { scale: 0.95, autoAlpha: 0 }, "-=0.2");
64```
65
66### 3) Scroll-scrub pinned section
67```js
68gsap.registerPlugin(ScrollTrigger);
69
70gsap.timeline({
71 scrollTrigger: {
72 trigger: ".story",
73 start: "top top",
74 end: "+=800",
75 scrub: 1,
76 pin: true,
77 },
78}).to(".story .panel", { xPercent: -200 });
79```
80
81## What to ask the user (if requirements unclear)
82- Is this a static site or SPA (React/Next/Vue)? Any page transitions?
83- Do we need scroll-driven sections (pin/scrub/snap)?
84- Performance constraints (mobile support, reduced motion)?