| name | gsap-scrolltrigger |
| description | Comprehensive skill for GSAP (GreenSock Animation Platform) and ScrollTrigger plugin. Use this skill when creating web animations, scroll-driven experiences, timelines, tweens, scroll-triggered animations, pinning, scrubbing, parallax effects, or animating DOM elements, SVG, Canvas, WebGL, or Three.js. Triggers on tasks involving GSAP, ScrollTrigger, smooth animations, scroll effects, or animation sequencing. |
GSAP & ScrollTrigger Development
Overview
GSAP (GreenSock Animation Platform) is the industry-leading JavaScript animation library for creating high-performance, production-quality animations. ScrollTrigger is GSAP's powerful plugin for scroll-driven animations. Together, they enable everything from simple UI transitions to complex scroll-based storytelling experiences.
Core Concepts
The Basics: Tweens
A tween is a single animation from point A to point B.
gsap.to(".box", {
x: 200,
rotation: 360,
duration: 1,
ease: "power2.inOut"
});
gsap.from(".box", {
opacity: 0,
y: -50,
duration: 0.8
});
gsap.fromTo(".box",
{ opacity: 0, scale: 0.5 },
{ opacity: 1, scale: 1, duration: 1 }
);
Timelines: Sequencing Animations
Timelines orchestrate multiple tweens in sequence or overlap.
const tl = gsap.timeline();
tl.to(".box1", { x: 100, duration: 1 })
.to(".box2", { y: 100, duration: 1 })
.to(".box3", { rotation: 360, duration: 1 });
tl.addLabel("start")
.to(".hero", { opacity: 1, duration: 1 })
.addLabel("reveal")
.to(".content", { y: 0, duration: 0.8 }, "reveal")
.to(".cta", { scale: 1, duration: 0.5 }, "reveal+=0.5");
Position Parameter (Timeline Timing)
Control when animations start within a timeline:
const tl = gsap.timeline();
tl.to(".box1", { x: 100 })
.to(".box2", { x: 100 });
tl.to(".box1", { x: 100 })
.to(".box2", { y: 100 }, 0);
tl.to(".box1", { x: 100, duration: 2 })
.to(".box2", { y: 100 }, "-=1");
.to(".box3", { rotation: 360 }, "+=0.5");
tl.to(".box1", { x: 100 }, 2.5);
ScrollTrigger Fundamentals
Basic Scroll Animation
gsap.registerPlugin(ScrollTrigger);
gsap.to(".box", {
x: 500,
scrollTrigger: {
trigger: ".box",
start: "top center",
end: "bottom center",
markers: true,
scrub: true,
toggleActions: "play none none reverse"
}
});
Start & End Positions
Format: "[trigger position] [viewport position]"
start: "top top"
start: "top center"
start: "top bottom"
start: "center center"
start: "top top+=100"
start: "top 80%"
end: "+=500"
end: "bottom top"
Scrubbing (Scroll-Synced Animation)
scrub: true
scrub: 1
scrub: 0.5
Toggle Actions
Control animation at four scroll points:
toggleActions: "play pause resume reset"
Common patterns:
toggleActions: "play none none none"
toggleActions: "play none none reverse"
toggleActions: "play complete reverse reset"
toggleActions: "restart pause resume pause"
Common Patterns
1. Fade In On Scroll
gsap.from(".fade-in", {
opacity: 0,
y: 50,
duration: 1,
scrollTrigger: {
trigger: ".fade-in",
start: "top 80%",
end: "top 50%",
scrub: 1,
once: true
}
});
2. Pin Element While Scrolling
ScrollTrigger.create({
trigger: ".panel",
start: "top top",
end: "+=500",
pin: true,
pinSpacing: true
});
3. Horizontal Scroll Section
const sections = gsap.utils.toArray(".panel");
gsap.to(sections, {
xPercent: -100 * (sections.length - 1),
ease: "none",
scrollTrigger: {
trigger: ".container",
pin: true,
scrub: 1,
end: () => "+=" + document.querySelector(".container").offsetWidth
}
});
4. Parallax Effect
gsap.to(".bg", {
y: 200,
ease: "none",
scrollTrigger: {
trigger: ".section",
start: "top bottom",
end: "bottom top",
scrub: true
}
});
gsap.to(".fg", {
y: -100,
ease: "none",
scrollTrigger: {
trigger: ".section",
start: "top bottom",
end: "bottom top",
scrub: true
}
});
5. Scroll-Triggered Timeline
const tl = gsap.timeline({
scrollTrigger: {
trigger: ".container",
start: "top top",
end: "+=500",
scrub: 1,
pin: true,
snap: {
snapTo: "labels",
duration: { min: 0.2, max: 3 },
delay: 0.2,
ease: "power1.inOut"
}
}
});
tl.addLabel("start")
.from(".title", { scale: 0.3, rotation: 45, autoAlpha: 0 })
.addLabel("color")
.from(".box", { backgroundColor: "#28a92b" })
.addLabel("spin")
.to(".box", { rotation: 360 })
.addLabel("end");
6. Batch Animations (Multiple Elements)
gsap.utils.toArray(".box").forEach((box, i) => {
gsap.from(box, {
y: 100,
opacity: 0,
scrollTrigger: {
trigger: box,
start: "top 80%",
end: "top 50%",
scrub: 1
}
});
});
ScrollTrigger.batch(".box", {
onEnter: batch => gsap.to(batch, { opacity: 1, y: 0, stagger: 0.15 }),
onLeave: batch => gsap.set(batch, { opacity: 0 }),
start: "top 80%",
once: true
});
7. Staggered Animations
gsap.from(".item", {
y: 50,
opacity: 0,
duration: 0.8,
stagger: 0.1,
scrollTrigger: {
trigger: ".grid",
start: "top 80%"
}
});
gsap.from(".item", {
scale: 0,
duration: 1,
stagger: {
each: 0.1,
from: "center",
grid: "auto",
ease: "power2.inOut"
}
});
Integration Patterns
With Three.js / WebGL
import * as THREE from 'three';
import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
gsap.registerPlugin(ScrollTrigger);
gsap.to(camera.position, {
x: 5,
y: 3,
z: 10,
scrollTrigger: {
trigger: "#section2",
start: "top top",
end: "bottom top",
scrub: 1,
onUpdate: () => camera.lookAt(scene.position)
}
});
gsap.to(mesh.rotation, {
y: Math.PI * 2,
scrollTrigger: {
trigger: "#section3",
start: "top bottom",
end: "bottom top",
scrub: true
}
});
gsap.to(material, {
opacity: 0,
scrollTrigger: {
trigger: "#section4",
start: "top center",
end: "center center",
scrub: 1
}
});
With React (useGSAP Hook)
import { useRef } from 'react';
import { useGSAP } from '@gsap/react';
import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
gsap.registerPlugin(ScrollTrigger);
function Component() {
const container = useRef();
const box = useRef();
useGSAP(() => {
gsap.to(box.current, {
x: 200,
scrollTrigger: {
trigger: box.current,
start: "top center",
end: "bottom center",
scrub: true,
markers: true
}
});
}, { scope: container });
return (
<div ref={container}>
<div ref={box} className="box">Animated Box</div>
</div>
);
}
Sharing Timeline in React
function App() {
const [tl, setTl] = useState();
useGSAP(() => {
const timeline = gsap.timeline();
setTl(timeline);
}, []);
return (
<div>
<Box timeline={tl} index={0} />
<Circle timeline={tl} index={1} />
</div>
);
}
function Box({ timeline, index }) {
const ref = useRef();
useGSAP(() => {
timeline && timeline.to(ref.current, { x: 100 }, index * 0.1);
}, [timeline, index]);
return <div ref={ref} className="box" />;
}
Locomotive Scroll Integration
import LocomotiveScroll from 'locomotive-scroll';
const scroller = new LocomotiveScroll({
el: document.querySelector('[data-scroll-container]'),
smooth: true
});
ScrollTrigger.scrollerProxy("[data-scroll-container]", {
scrollTop(value) {
return arguments.length ? scroller.scrollTo(value, 0, 0) : scroller.scroll.instance.scroll.y;
},
getBoundingClientRect() {
return {top: 0, left: 0, width: window.innerWidth, height: window.innerHeight};
},
pinType: document.querySelector("[data-scroll-container]").style.transform ? "transform" : "fixed"
});
ScrollTrigger.addEventListener("refresh", () => scroller.update());
ScrollTrigger.refresh();
Advanced Techniques
Image Sequence Scrubbing
const canvas = document.querySelector("canvas");
const context = canvas.getContext("2d");
const images = [];
const imageCount = 147;
const currentFrame = { value: 0 };
for (let i = 0; i < imageCount; i++) {
const img = new Image();
img.src = `./frames/frame_${i.toString().padStart(4, '0')}.jpg`;
images.push(img);
}
images[0].onload = () => {
canvas.width = images[0].width;
canvas.height = images[0].height;
render();
};
function render() {
context.clearRect(0, 0, canvas.width, canvas.height);
context.drawImage(images[Math.floor(currentFrame.value)], 0, 0);
}
gsap.to(currentFrame, {
value: imageCount - 1,
snap: "value",
ease: "none",
scrollTrigger: {
trigger: canvas,
start: "top top",
end: "+=500%",
scrub: true,
pin: true
},
onUpdate: render
});
Smooth Scroll to Element
gsap.registerPlugin(ScrollToPlugin);
gsap.to(window, {
duration: 1,
scrollTo: "#section2",
ease: "power2.inOut"
});
gsap.to(window, {
duration: 1.5,
scrollTo: { y: "#section2", offsetY: 50 },
ease: "expo.inOut"
});
gsap.to(".container", {
duration: 2,
scrollTo: { x: 1000, autoKill: true }
});
Conditional Animations (Media Queries)
ScrollTrigger.matchMedia({
"(min-width: 800px)": function() {
gsap.to(".box", {
x: 500,
scrollTrigger: {
trigger: ".box",
start: "top center",
end: "bottom top",
scrub: true
}
});
},
"(max-width: 799px)": function() {
gsap.to(".box", {
y: 200,
scrollTrigger: {
trigger: ".box",
start: "top 80%",
scrub: 1
}
});
}
});
Performance Best Practices
1. Use will-change CSS
.animated-element {
will-change: transform, opacity;
}
2. Limit Repaints
gsap.to(".box", { x: 100, opacity: 0.5 });
3. Dispose of ScrollTriggers
const trigger = ScrollTrigger.create({ });
trigger.kill();
ScrollTrigger.getAll().forEach(t => t.kill());
useGSAP(() => {
const tween = gsap.to(".box", { });
return () => {
tween.kill();
};
}, []);
4. Debounce Resize
ScrollTrigger handles this automatically, but for custom resize logic:
let resizeTimer;
window.addEventListener("resize", () => {
clearTimeout(resizeTimer);
resizeTimer = setTimeout(() => {
ScrollTrigger.refresh();
}, 250);
});
5. Use invalidateOnRefresh
For dynamic values that change on resize:
gsap.to(".box", {
x: () => window.innerWidth / 2,
scrollTrigger: {
trigger: ".box",
start: "top center",
invalidateOnRefresh: true
}
});
Common Pitfalls
1. Multiple Tweens on Same Element
gsap.to('h1', { x: 100, scrollTrigger: { } });
gsap.to('h1', { x: 200, scrollTrigger: { } });
gsap.fromTo('h1', { x: 100 }, { x: 200, scrollTrigger: { } });
gsap.to('h1', { x: 200, immediateRender: false, scrollTrigger: { } });
const tl = gsap.timeline({ scrollTrigger: { } });
tl.to('h1', { x: 100 })
.to('h1', { x: 200 });
2. Not Using Loops for Multiple Elements
gsap.to('.section', {
y: -100,
scrollTrigger: { trigger: '.section', scrub: true }
});
gsap.utils.toArray('.section').forEach(section => {
gsap.to(section, {
y: -100,
scrollTrigger: { trigger: section, scrub: true }
});
});
3. Forgetting to Register Plugins
import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
import { ScrollToPlugin } from 'gsap/ScrollToPlugin';
gsap.registerPlugin(ScrollTrigger, ScrollToPlugin);
4. Nested ScrollTriggers in Timelines
const tl = gsap.timeline();
tl.to('.box1', { x: 100, scrollTrigger: { } })
.to('.box2', { y: 100, scrollTrigger: { } });
const tl = gsap.timeline({
scrollTrigger: { }
});
tl.to('.box1', { x: 100 })
.to('.box2', { y: 100 });
Easing Reference
ease: "power1.out"
ease: "power2.inOut"
ease: "power3.in"
ease: "power4.out"
ease: "elastic.out"
ease: "back.out"
ease: "bounce.out"
ease: "circ.inOut"
ease: "expo.inOut"
ease: "none"
ScrollTrigger Methods
ScrollTrigger.refresh();
const triggers = ScrollTrigger.getAll();
const st = ScrollTrigger.getById("myTrigger");
st.kill();
st.scroll(500);
st.enable();
st.disable();
ScrollTrigger.config({
limitCallbacks: true,
syncInterval: 15
});
ScrollTrigger.defaults({
markers: true
});
Resources
This skill includes bundled resources:
references/
api_reference.md: Quick API reference (tween methods, timeline methods, ScrollTrigger properties)
easing_guide.md: Visual easing reference with use cases
common_patterns.md: Copy-paste patterns for common scenarios
scripts/
generate_animation.py: Generate boilerplate GSAP code
timeline_builder.py: Interactive timeline sequence builder
assets/
starter_scroll/: Complete scroll-driven site template
easings/: Easing visualization HTML tool
examples/: Real-world ScrollTrigger examples
When to Use This Skill
Use this skill when:
- Creating smooth web animations
- Building scroll-driven experiences
- Implementing parallax effects
- Sequencing complex animations
- Animating DOM, SVG, Canvas, or WebGL
- Integrating animations with Three.js or React
- Building scrollytelling websites
- Creating interactive UI transitions
For Three.js-specific animations, also reference the threejs-webgl skill.
For React components with built-in animations, reference the motion-framer skill.