gsap-scrolltrigger

OverviewHistoryStatsSecurity

npx skills add freshtechbro/claudedesignskills --skill gsap-scrolltrigger

Documentation

SKILL.md

npx skills add ...

Documentation

SKILL.md

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.

npx skills add freshtechbro/claudedesignskills --skill gsap-scrolltrigger

Documentation

SKILL.mdView source

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.

// Animate TO a state (from current)
gsap.to(".box", {
  x: 200,
  rotation: 360,
  duration: 1,
  ease: "power2.inOut"
});
 
// Animate FROM a state (to current)
gsap.from(".box", {
  opacity: 0,
  y: -50,
  duration: 0.8
});
 
// Animate FROM-TO (define both start and end)
gsap.fromTo(".box",
  { opacity: 0, scale: 0.5 }, // FROM
  { opacity: 1, scale: 1, duration: 1 } // TO
);

Timelines: Sequencing Animations

Timelines orchestrate multiple tweens in sequence or overlap.

const tl = gsap.timeline();
 
// Sequential by default
tl.to(".box1", { x: 100, duration: 1 })
  .to(".box2", { y: 100, duration: 1 })
  .to(".box3", { rotation: 360, duration: 1 });
 
// With labels for organization
tl.addLabel("start")
  .to(".hero", { opacity: 1, duration: 1 })
  .addLabel("reveal")
  .to(".content", { y: 0, duration: 0.8 }, "reveal") // Start at "reveal" label
  .to(".cta", { scale: 1, duration: 0.5 }, "reveal+=0.5"); // 0.5s after "reveal"

Position Parameter (Timeline Timing)

Control when animations start within a timeline:

const tl = gsap.timeline();
 
// Default: One after another
tl.to(".box1", { x: 100 })
  .to(".box2", { x: 100 }); // Starts after box1 finishes
 
// Start at the same time
tl.to(".box1", { x: 100 })
  .to(".box2", { y: 100 }, 0); // Starts at 0 seconds
 
// Relative positioning
tl.to(".box1", { x: 100, duration: 2 })
  .to(".box2", { y: 100 }, "-=1"); // Starts 1 second before box1 ends
  .to(".box3", { rotation: 360 }, "+=0.5"); // Starts 0.5s after box2 finishes
 
// At a specific time
tl.to(".box1", { x: 100 }, 2.5); // Starts at 2.5 seconds

ScrollTrigger Fundamentals

Basic Scroll Animation

gsap.registerPlugin(ScrollTrigger);
 
gsap.to(".box", {
  x: 500,
  scrollTrigger: {
    trigger: ".box",
    start: "top center", // When top of trigger hits center of viewport
    end: "bottom center",
    markers: true, // Development only - shows start/end positions
    scrub: true, // Links animation to scrollbar
    toggleActions: "play none none reverse" // onEnter onLeave onEnterBack onLeaveBack
  }
});

Start & End Positions

Format: "[trigger position] [viewport position]"

// Common patterns
start: "top top"      // Trigger top hits viewport top
start: "top center"   // Trigger top hits viewport center (default)
start: "top bottom"   // Trigger top hits viewport bottom
start: "center center" // Trigger center hits viewport center
 
// With offsets
start: "top top+=100"   // 100px below viewport top
start: "top 80%"        // 80% down the viewport
end: "+=500"            // 500px after start position
end: "bottom top"       // Trigger bottom hits viewport top

Scrubbing (Scroll-Synced Animation)

// Boolean: Direct link to scrollbar (immediate)
scrub: true
 
// Number: Smoothing delay in seconds
scrub: 1  // Takes 1 second to "catch up" to scrollbar
scrub: 0.5 // Faster, tighter feel

Toggle Actions

Control animation at four scroll points:

toggleActions: "play pause resume reset"
// onEnter | onLeave | onEnterBack | onLeaveBack
 
// Actions: play, pause, resume, restart, reset, complete, reverse, none

Common patterns:

toggleActions: "play none none none"       // Play once on enter
toggleActions: "play none none reverse"    // Play forward, reverse back
toggleActions: "play complete reverse reset" // Full control
toggleActions: "restart pause resume pause"  // Restart on each enter

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 // Only animate once
  }
});

2. Pin Element While Scrolling

ScrollTrigger.create({
  trigger: ".panel",
  start: "top top",
  end: "+=500", // Pin for 500px of scrolling
  pin: true,
  pinSpacing: true // Add spacing (default 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

// Slower movement (background layer)
gsap.to(".bg", {
  y: 200,
  ease: "none",
  scrollTrigger: {
    trigger: ".section",
    start: "top bottom",
    end: "bottom top",
    scrub: true
  }
});
 
// Faster movement (foreground layer)
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", // Snap to timeline 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)

// Loop through 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
    }
  });
});
 
// Or use ScrollTrigger.batch
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, // 0.1s between each item
  scrollTrigger: {
    trigger: ".grid",
    start: "top 80%"
  }
});
 
// Advanced stagger
gsap.from(".item", {
  scale: 0,
  duration: 1,
  stagger: {
    each: 0.1,
    from: "center", // "start", "center", "end", "edges", or index number
    grid: "auto", // For grid layouts
    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);
 
// Animate camera
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)
  }
});
 
// Animate mesh rotation
gsap.to(mesh.rotation, {
  y: Math.PI * 2,
  scrollTrigger: {
    trigger: "#section3",
    start: "top bottom",
    end: "bottom top",
    scrub: true
  }
});
 
// Animate material properties
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 }); // Scoping for cleanup
 
  return (
    <div ref={container}>
      <div ref={box} className="box">Animated Box</div>
    </div>
  );
}

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);
 
// Scroll to element
gsap.to(window, {
  duration: 1,
  scrollTo: "#section2",
  ease: "power2.inOut"
});
 
// With offset
gsap.to(window, {
  duration: 1.5,
  scrollTo: { y: "#section2", offsetY: 50 },
  ease: "expo.inOut"
});
 
// Horizontal scroll
gsap.to(".container", {
  duration: 2,
  scrollTo: { x: 1000, autoKill: true }
});

Conditional Animations (Media Queries)

ScrollTrigger.matchMedia({
  // Desktop
  "(min-width: 800px)": function() {
    gsap.to(".box", {
      x: 500,
      scrollTrigger: {
        trigger: ".box",
        start: "top center",
        end: "bottom top",
        scrub: true
      }
    });
  },
 
  // Mobile
  "(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

// Good: Animate transform/opacity (GPU accelerated)
gsap.to(".box", { x: 100, opacity: 0.5 });
 
// Avoid: Animating layout properties
// gsap.to(".box", { width: 500, height: 300 }); // Causes reflow

3. Dispose of ScrollTriggers

// Kill individual trigger
const trigger = ScrollTrigger.create({ /* ... */ });
trigger.kill();
 
// Kill all triggers
ScrollTrigger.getAll().forEach(t => t.kill());
 
// In React with cleanup
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, // Dynamic value
  scrollTrigger: {
    trigger: ".box",
    start: "top center",
    invalidateOnRefresh: true // Recalculate x on resize
  }
});

Common Pitfalls

1. Multiple Tweens on Same Element

// Problem: Second tween conflicts with first
gsap.to('h1', { x: 100, scrollTrigger: { /* ... */ } });
gsap.to('h1', { x: 200, scrollTrigger: { /* ... */ } }); // Jumps!
 
// Solution 1: Use fromTo
gsap.fromTo('h1', { x: 100 }, { x: 200, scrollTrigger: { /* ... */ } });
 
// Solution 2: Use immediateRender: false
gsap.to('h1', { x: 200, immediateRender: false, scrollTrigger: { /* ... */ } });
 
// Solution 3: Apply ScrollTrigger to timeline
const tl = gsap.timeline({ scrollTrigger: { /* ... */ } });
tl.to('h1', { x: 100 })
  .to('h1', { x: 200 });

2. Not Using Loops for Multiple Elements

// Wrong: Animates all at once
gsap.to('.section', {
  y: -100,
  scrollTrigger: { trigger: '.section', scrub: true }
});
 
// Right: Loop for individual triggers
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); // Must register!

4. Nested ScrollTriggers in Timelines

// Wrong: ScrollTriggers on individual tweens in timeline
const tl = gsap.timeline();
tl.to('.box1', { x: 100, scrollTrigger: { /* ... */ } }) // Don't do this!
  .to('.box2', { y: 100, scrollTrigger: { /* ... */ } });
 
// Right: ScrollTrigger on parent timeline
const tl = gsap.timeline({
  scrollTrigger: { /* ... */ }
});
tl.to('.box1', { x: 100 })
  .to('.box2', { y: 100 });

Easing Reference

// Power easings (most common)
ease: "power1.out"  // Subtle deceleration
ease: "power2.inOut" // Smooth acceleration/deceleration
ease: "power3.in"   // Strong acceleration
ease: "power4.out"  // Very strong deceleration
 
// Special easings
ease: "elastic.out"  // Bouncy overshoot
ease: "back.out"     // Slight overshoot
ease: "bounce.out"   // Bouncing effect
ease: "circ.inOut"   // Circular motion feel
ease: "expo.inOut"   // Exponential (dramatic)
 
// Linear (for scrubbed scroll animations)
ease: "none"

ScrollTrigger Methods

// Refresh all ScrollTriggers (after DOM changes)
ScrollTrigger.refresh();
 
// Get all ScrollTriggers
const triggers = ScrollTrigger.getAll();
 
// Get specific trigger by ID
const st = ScrollTrigger.getById("myTrigger");
 
// Kill trigger
st.kill();
 
// Update trigger
st.scroll(500); // Programmatically set scroll position
st.enable();
st.disable();
 
// Global ScrollTrigger config
ScrollTrigger.config({
  limitCallbacks: true, // Improve performance
  syncInterval: 15 // Throttle scroll checks (ms)
});
 
// Debug mode
ScrollTrigger.defaults({
  markers: true // Show markers on all triggers
});

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.

npx skills add freshtechbro/claudedesignskills --skill gsap-scrolltrigger

Documentation

SKILL.md

npx skills add freshtechbro/claudedesignskills --skill gsap-scrolltrigger

Documentation

SKILL.mdView source

GSAP & ScrollTrigger Development

Overview

Core Concepts

The Basics: Tweens

A tween is a single animation from point A to point B.

// Animate TO a state (from current)
gsap.to(".box", {
  x: 200,
  rotation: 360,
  duration: 1,
  ease: "power2.inOut"
});
 
// Animate FROM a state (to current)
gsap.from(".box", {
  opacity: 0,
  y: -50,
  duration: 0.8
});
 
// Animate FROM-TO (define both start and end)
gsap.fromTo(".box",
  { opacity: 0, scale: 0.5 }, // FROM
  { opacity: 1, scale: 1, duration: 1 } // TO
);

Timelines: Sequencing Animations

Timelines orchestrate multiple tweens in sequence or overlap.

const tl = gsap.timeline();
 
// Sequential by default
tl.to(".box1", { x: 100, duration: 1 })
  .to(".box2", { y: 100, duration: 1 })
  .to(".box3", { rotation: 360, duration: 1 });
 
// With labels for organization
tl.addLabel("start")
  .to(".hero", { opacity: 1, duration: 1 })
  .addLabel("reveal")
  .to(".content", { y: 0, duration: 0.8 }, "reveal") // Start at "reveal" label
  .to(".cta", { scale: 1, duration: 0.5 }, "reveal+=0.5"); // 0.5s after "reveal"

Position Parameter (Timeline Timing)

Control when animations start within a timeline:

const tl = gsap.timeline();
 
// Default: One after another
tl.to(".box1", { x: 100 })
  .to(".box2", { x: 100 }); // Starts after box1 finishes
 
// Start at the same time
tl.to(".box1", { x: 100 })
  .to(".box2", { y: 100 }, 0); // Starts at 0 seconds
 
// Relative positioning
tl.to(".box1", { x: 100, duration: 2 })
  .to(".box2", { y: 100 }, "-=1"); // Starts 1 second before box1 ends
  .to(".box3", { rotation: 360 }, "+=0.5"); // Starts 0.5s after box2 finishes
 
// At a specific time
tl.to(".box1", { x: 100 }, 2.5); // Starts at 2.5 seconds

ScrollTrigger Fundamentals

Basic Scroll Animation

gsap.registerPlugin(ScrollTrigger);
 
gsap.to(".box", {
  x: 500,
  scrollTrigger: {
    trigger: ".box",
    start: "top center", // When top of trigger hits center of viewport
    end: "bottom center",
    markers: true, // Development only - shows start/end positions
    scrub: true, // Links animation to scrollbar
    toggleActions: "play none none reverse" // onEnter onLeave onEnterBack onLeaveBack
  }
});

Start & End Positions

Format: "[trigger position] [viewport position]"

// Common patterns
start: "top top"      // Trigger top hits viewport top
start: "top center"   // Trigger top hits viewport center (default)
start: "top bottom"   // Trigger top hits viewport bottom
start: "center center" // Trigger center hits viewport center
 
// With offsets
start: "top top+=100"   // 100px below viewport top
start: "top 80%"        // 80% down the viewport
end: "+=500"            // 500px after start position
end: "bottom top"       // Trigger bottom hits viewport top

Scrubbing (Scroll-Synced Animation)

// Boolean: Direct link to scrollbar (immediate)
scrub: true
 
// Number: Smoothing delay in seconds
scrub: 1  // Takes 1 second to "catch up" to scrollbar
scrub: 0.5 // Faster, tighter feel

Toggle Actions

Control animation at four scroll points:

toggleActions: "play pause resume reset"
// onEnter | onLeave | onEnterBack | onLeaveBack
 
// Actions: play, pause, resume, restart, reset, complete, reverse, none

Common patterns:

toggleActions: "play none none none"       // Play once on enter
toggleActions: "play none none reverse"    // Play forward, reverse back
toggleActions: "play complete reverse reset" // Full control
toggleActions: "restart pause resume pause"  // Restart on each enter

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 // Only animate once
  }
});

2. Pin Element While Scrolling

ScrollTrigger.create({
  trigger: ".panel",
  start: "top top",
  end: "+=500", // Pin for 500px of scrolling
  pin: true,
  pinSpacing: true // Add spacing (default 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

// Slower movement (background layer)
gsap.to(".bg", {
  y: 200,
  ease: "none",
  scrollTrigger: {
    trigger: ".section",
    start: "top bottom",
    end: "bottom top",
    scrub: true
  }
});
 
// Faster movement (foreground layer)
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", // Snap to timeline 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)

// Loop through 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
    }
  });
});
 
// Or use ScrollTrigger.batch
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, // 0.1s between each item
  scrollTrigger: {
    trigger: ".grid",
    start: "top 80%"
  }
});
 
// Advanced stagger
gsap.from(".item", {
  scale: 0,
  duration: 1,
  stagger: {
    each: 0.1,
    from: "center", // "start", "center", "end", "edges", or index number
    grid: "auto", // For grid layouts
    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);
 
// Animate camera
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)
  }
});
 
// Animate mesh rotation
gsap.to(mesh.rotation, {
  y: Math.PI * 2,
  scrollTrigger: {
    trigger: "#section3",
    start: "top bottom",
    end: "bottom top",
    scrub: true
  }
});
 
// Animate material properties
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 }); // Scoping for cleanup
 
  return (
    <div ref={container}>
      <div ref={box} className="box">Animated Box</div>
    </div>
  );
}

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);
 
// Scroll to element
gsap.to(window, {
  duration: 1,
  scrollTo: "#section2",
  ease: "power2.inOut"
});
 
// With offset
gsap.to(window, {
  duration: 1.5,
  scrollTo: { y: "#section2", offsetY: 50 },
  ease: "expo.inOut"
});
 
// Horizontal scroll
gsap.to(".container", {
  duration: 2,
  scrollTo: { x: 1000, autoKill: true }
});

Conditional Animations (Media Queries)

ScrollTrigger.matchMedia({
  // Desktop
  "(min-width: 800px)": function() {
    gsap.to(".box", {
      x: 500,
      scrollTrigger: {
        trigger: ".box",
        start: "top center",
        end: "bottom top",
        scrub: true
      }
    });
  },
 
  // Mobile
  "(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

// Good: Animate transform/opacity (GPU accelerated)
gsap.to(".box", { x: 100, opacity: 0.5 });
 
// Avoid: Animating layout properties
// gsap.to(".box", { width: 500, height: 300 }); // Causes reflow

3. Dispose of ScrollTriggers

// Kill individual trigger
const trigger = ScrollTrigger.create({ /* ... */ });
trigger.kill();
 
// Kill all triggers
ScrollTrigger.getAll().forEach(t => t.kill());
 
// In React with cleanup
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, // Dynamic value
  scrollTrigger: {
    trigger: ".box",
    start: "top center",
    invalidateOnRefresh: true // Recalculate x on resize
  }
});

Common Pitfalls

1. Multiple Tweens on Same Element

// Problem: Second tween conflicts with first
gsap.to('h1', { x: 100, scrollTrigger: { /* ... */ } });
gsap.to('h1', { x: 200, scrollTrigger: { /* ... */ } }); // Jumps!
 
// Solution 1: Use fromTo
gsap.fromTo('h1', { x: 100 }, { x: 200, scrollTrigger: { /* ... */ } });
 
// Solution 2: Use immediateRender: false
gsap.to('h1', { x: 200, immediateRender: false, scrollTrigger: { /* ... */ } });
 
// Solution 3: Apply ScrollTrigger to timeline
const tl = gsap.timeline({ scrollTrigger: { /* ... */ } });
tl.to('h1', { x: 100 })
  .to('h1', { x: 200 });

2. Not Using Loops for Multiple Elements

// Wrong: Animates all at once
gsap.to('.section', {
  y: -100,
  scrollTrigger: { trigger: '.section', scrub: true }
});
 
// Right: Loop for individual triggers
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); // Must register!

4. Nested ScrollTriggers in Timelines

// Wrong: ScrollTriggers on individual tweens in timeline
const tl = gsap.timeline();
tl.to('.box1', { x: 100, scrollTrigger: { /* ... */ } }) // Don't do this!
  .to('.box2', { y: 100, scrollTrigger: { /* ... */ } });
 
// Right: ScrollTrigger on parent timeline
const tl = gsap.timeline({
  scrollTrigger: { /* ... */ }
});
tl.to('.box1', { x: 100 })
  .to('.box2', { y: 100 });

Easing Reference

// Power easings (most common)
ease: "power1.out"  // Subtle deceleration
ease: "power2.inOut" // Smooth acceleration/deceleration
ease: "power3.in"   // Strong acceleration
ease: "power4.out"  // Very strong deceleration
 
// Special easings
ease: "elastic.out"  // Bouncy overshoot
ease: "back.out"     // Slight overshoot
ease: "bounce.out"   // Bouncing effect
ease: "circ.inOut"   // Circular motion feel
ease: "expo.inOut"   // Exponential (dramatic)
 
// Linear (for scrubbed scroll animations)
ease: "none"

ScrollTrigger Methods

// Refresh all ScrollTriggers (after DOM changes)
ScrollTrigger.refresh();
 
// Get all ScrollTriggers
const triggers = ScrollTrigger.getAll();
 
// Get specific trigger by ID
const st = ScrollTrigger.getById("myTrigger");
 
// Kill trigger
st.kill();
 
// Update trigger
st.scroll(500); // Programmatically set scroll position
st.enable();
st.disable();
 
// Global ScrollTrigger config
ScrollTrigger.config({
  limitCallbacks: true, // Improve performance
  syncInterval: 15 // Throttle scroll checks (ms)
});
 
// Debug mode
ScrollTrigger.defaults({
  markers: true // Show markers on all triggers
});

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.

gsap-scrolltrigger

Documentation

Documentation

gsap-scrolltrigger

Documentation

GSAP & ScrollTrigger Development

Overview

Core Concepts

The Basics: Tweens

Timelines: Sequencing Animations

Position Parameter (Timeline Timing)

ScrollTrigger Fundamentals

Basic Scroll Animation

Start & End Positions

Scrubbing (Scroll-Synced Animation)

Toggle Actions

Common Patterns

1. Fade In On Scroll

2. Pin Element While Scrolling

3. Horizontal Scroll Section

4. Parallax Effect

5. Scroll-Triggered Timeline

6. Batch Animations (Multiple Elements)

7. Staggered Animations

Integration Patterns

With Three.js / WebGL

With React (useGSAP Hook)

Sharing Timeline in React

Locomotive Scroll Integration

Advanced Techniques

Image Sequence Scrubbing

Smooth Scroll to Element

Conditional Animations (Media Queries)

Performance Best Practices

1. Use will-change CSS

2. Limit Repaints

3. Dispose of ScrollTriggers

4. Debounce Resize

5. Use invalidateOnRefresh

Common Pitfalls

1. Multiple Tweens on Same Element

2. Not Using Loops for Multiple Elements

3. Forgetting to Register Plugins

4. Nested ScrollTriggers in Timelines

Easing Reference

ScrollTrigger Methods

Resources

references/

scripts/

assets/

When to Use This Skill

Documentation

Documentation

GSAP & ScrollTrigger Development

Overview

Core Concepts

The Basics: Tweens

Timelines: Sequencing Animations

Position Parameter (Timeline Timing)

ScrollTrigger Fundamentals

Basic Scroll Animation

Start & End Positions

Scrubbing (Scroll-Synced Animation)

Toggle Actions

Common Patterns

1. Fade In On Scroll

2. Pin Element While Scrolling

3. Horizontal Scroll Section

4. Parallax Effect

5. Scroll-Triggered Timeline

6. Batch Animations (Multiple Elements)

7. Staggered Animations

Integration Patterns

With Three.js / WebGL

With React (useGSAP Hook)

Sharing Timeline in React

Locomotive Scroll Integration

Advanced Techniques

Image Sequence Scrubbing

Smooth Scroll to Element

1. Use `will-change` CSS

5. Use `invalidateOnRefresh`

1. Use `will-change` CSS

5. Use `invalidateOnRefresh`