GSAP ScrollTrigger

When to Use This Skill

Registering the Plugin

gsap.registerPlugin(ScrollTrigger);

Basic Trigger

gsap.to(".box", {
  x: 500,
  duration: 1,
  scrollTrigger: {
    trigger: ".box",
    start: "top center",   // when top of trigger hits center of viewport
    end: "bottom center",  // when the bottom of the trigger hits the center of the viewport
    toggleActions: "play reverse play reverse" // onEnter play, onLeave reverse, onEnterBack play, onLeaveBack reverse
  }
});

Key config options

ScrollTrigger.create({
  trigger: "#id",
  start: "top top",
  end: "bottom 50%+=100px",
  onUpdate: (self) => console.log(self.progress.toFixed(3), self.direction)
});

ScrollTrigger.batch()

• triggers: selector text (e.g. ".box") or Array of elements.
• vars: standard ScrollTrigger config (start, end, once, callbacks, etc.). Do not pass trigger (targets are the triggers) or animation-related options: animation, invalidateOnRefresh, onSnapComplete, onScrubComplete, scrub, snap, toggleActions.

1. targets — Array of trigger elements that fired this callback within the interval.
2. scrollTriggers — Array of the ScrollTrigger instances that fired. Use for progress, direction, or kill().

• interval (Number) — Max time in seconds to collect each batch. Default is roughly one requestAnimationFrame. When the first callback of a type fires, the timer starts; the batch is delivered when the interval elapses or when batchMax is reached.
• batchMax (Number | Function) — Max elements per batch. When full, the callback fires and the next batch starts. Use a function that returns a number for responsive layouts; it runs on refresh (resize, tab focus, etc.).

ScrollTrigger.batch(".box", {
  onEnter: (elements, triggers) => {
    gsap.to(elements, { opacity: 1, y: 0, stagger: 0.15 });
  },
  onLeave: (elements, triggers) => {
    gsap.to(elements, { opacity: 0, y: 100 });
  },
  start: "top 80%",
  end: "bottom 20%"
});

ScrollTrigger.batch(".card", {
  interval: 0.1,
  batchMax: 4,
  onEnter: (batch) => gsap.to(batch, { opacity: 1, y: 0, stagger: 0.1, overwrite: true }),
  onLeaveBack: (batch) => gsap.set(batch, { opacity: 0, y: 50, overwrite: true })
});

ScrollTrigger.scrollerProxy()

• scroller: selector or element (e.g. "body", ".container").
• vars: object with scrollTop and/or scrollLeft functions. Each acts as getter and setter: when called with an argument, it is a setter; when called with no argument, it returns the current value (getter). At least one of scrollTop or scrollLeft is required.

• getBoundingClientRect — Function returning { top, left, width, height } for the scroller (often { top: 0, left: 0, width: window.innerWidth, height: window.innerHeight } for the viewport). Needed when the scroller’s real rect is not the default.
• scrollWidth / scrollHeight — Getter/setter functions (same pattern: argument = setter, no argument = getter) when the library exposes different dimensions.
• fixedMarkers (Boolean) — When true, markers are treated as position: fixed. Useful when the scroller is translated (e.g. by a smooth-scroll lib) and markers move incorrectly.
• pinType — "fixed" or "transform". Controls how pinning is applied for this scroller. Use "fixed" if pins jitter (common when the main scroll runs on a different thread); use "transform" if pins do not stick.

// Example: proxy body scroll to a third-party scroll instance
ScrollTrigger.scrollerProxy(document.body, {
  scrollTop(value) {
    if (arguments.length) scrollbar.scrollTop = value;
    return scrollbar.scrollTop;
  },
  getBoundingClientRect() {
    return { top: 0, left: 0, width: window.innerWidth, height: window.innerHeight };
  }
});
scrollbar.addListener(ScrollTrigger.update);

Scrub

gsap.to(".box", {
  x: 500,
  scrollTrigger: {
    trigger: ".box",
    start: "top center",
    end: "bottom center",
    scrub: true        // or number (smoothness delay in seconds), so 0.5 means it'd take 0.5 seconds to "catch up" to the current scroll position.
  }
});

Pinning

scrollTrigger: {
  trigger: ".section",
  start: "top top",
  end: "+=1000",   // pin for 1000px scroll
  pin: true,
  scrub: 1
}

• pinSpacing — default true; adds spacer element so layout doesn’t collapse when the pinned element is set to position: fixed. Set pinSpacing: false only when layout is handled separately.

Markers (Development)

scrollTrigger: {
  trigger: ".box",
  start: "top center",
  end: "bottom center",
  markers: true
}

Timeline + ScrollTrigger

const tl = gsap.timeline({
  scrollTrigger: {
    trigger: ".container",
    start: "top top",
    end: "+=2000",
    scrub: 1,
    pin: true
  }
});
tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });

Horizontal scroll (containerAnimation)

1. Pin the section (trigger = the full-viewport panel).
2. Build a tween that animates the inner content’s x or xPercent (e.g. to x: () => (targets.length - 1) * -window.innerWidth or a negative xPercent to move left). Use ease: "none" on that tween.
3. Attach ScrollTrigger to that tween with pin: true, scrub: true
4. To trigger things based on the horizontal movement caused by that tween, set containerAnimation to that tween.

const scrollingEl = document.querySelector(".horizontal-el");
// Panel = pinned viewport-sized section. .horizontal-wrap = inner content that moves left.
const scrollTween = gsap.to(scrollingEl, { 
  xPercent: () => Max.max(0, window.innerWidth - scrollingEl.offsetWidth), 
  ease: "none", // ease: "none" is required
  scrollTrigger: {
    trigger: scrollingEl,
    pin: scrollingEl.parentNode, // wrapper so that we're not animating the pinned element
    start: "top top",
    end: "+=1000"
  }
}); 

// other tweens that trigger based on horizontal movement should reference the containerAnimation:
gsap.to(".nested-el-1", {
  y: 100,
  scrollTrigger: {
    containerAnimation: scrollTween, // IMPORTANT
    trigger: ".nested-wrapper-1",
    start: "left center", // based on horizontal movement
    toggleActions: "play none none reset"
  }
});

Refresh and Cleanup

• ScrollTrigger.refresh() — recalculate positions (e.g. after DOM/layout changes, fonts loaded, or dynamic content). Automatically called on viewport resize, debounced 200ms. Refresh runs in creation order (or by refreshPriority); create ScrollTriggers top-to-bottom on the page or set refreshPriority so they refresh in that order.
• When removing animated elements or changing pages (e.g. in SPAs), kill associated ScrollTrigger instances so they don’t run on stale elements:

ScrollTrigger.getAll().forEach(t => t.kill());
// or kill by the id assigned to the ScrollTrigger in its config object like {id: "my-id", ...}
ScrollTrigger.getById("my-id")?.kill();

Official GSAP best practices

• ✅ gsap.registerPlugin(ScrollTrigger) once before any ScrollTrigger usage.
• ✅ Call ScrollTrigger.refresh() after DOM/layout changes (new content, images, fonts) that affect trigger positions. Whenever the viewport is resized, ScrollTrigger.refresh() is automatically called (debounced 200ms)
• ✅ In React, use the useGSAP() hook to ensure that all ScrollTriggers and GSAP animations are reverted and cleaned up when necessary, or use a gsap.context() to do it manually in a useEffect/useLayoutEffect cleanup function.
• ✅ Use scrub for scroll-linked progress or toggleActions for discrete play/reverse; do not use both on the same trigger.
• ✅ For fake horizontal scroll with containerAnimation, use ease: "none" on the horizontal tween/timeline so scroll and horizontal position stay in sync.
• ✅ Create ScrollTriggers in the order they appear on the page (top to bottom, scroll 0 → max). When they are created in a different order (e.g. dynamic or async), set refreshPriority on each so they are refreshed in that same top-to-bottom order (first section on page = lower number).

Do Not

• ❌ Put ScrollTrigger on a child tween when it's part of a timeline; put it on the timeline or a top-level tween only. Wrong: gsap.timeline().to(".a", { scrollTrigger: {...} }). Correct: gsap.timeline({ scrollTrigger: {...} }).to(".a", { x: 100 }).
• ❌ Forget to call ScrollTrigger.refresh() after DOM/layout changes (new content, images, fonts) that affect trigger positions; viewport resize is auto-handled, but dynamic content is not.
• ❌ Nest ScrollTriggered animations inside of a parent timeline. ScrollTriggers should only exist on top-level animations.
• ❌ Forget to gsap.registerPlugin(ScrollTrigger) before using ScrollTrigger.
• ❌ Use scrub and toggleActions together on the same ScrollTrigger; choose one behavior. If both exist, scrub wins.
• ❌ Use an ease other than "none" on the horizontal animation when using containerAnimation for fake horizontal scroll; it breaks the 1:1 scroll-to-position mapping.
• ❌ Create ScrollTriggers in random or async order without setting refreshPriority; refresh runs in creation order (or by refreshPriority), and wrong order can affect layout (e.g. pin spacing). Create them top-to-bottom or assign refreshPriority so they refresh in page order.
• ❌ Leave markers: true in production.
• ❌ Forget refresh() after layout changes (new content, images, fonts) that affect trigger positions; viewport resize is handled automatically.

Learn More