Timelines

Sequenced animation chains with control:

const tl = gsap.timeline({ defaults: { duration: 0.6, ease: "power3.out" } });
tl.from(".hero-title", { y: 60, opacity: 0 })
  .from(".hero-subtitle", { y: 40, opacity: 0 }, "-=0.3")
  .from(".hero-cta", { y: 30, opacity: 0, scale: 0.95 }, "-=0.2")
  .addLabel("heroComplete");

ScrollTrigger

Ties animation progress to scroll position:

gsap.registerPlugin(ScrollTrigger);

gsap.to(".parallax-bg", {
  y: -200,
  scrollTrigger: {
    trigger: ".parallax-section",
    start: "top bottom",
    end: "bottom top",
    scrub: true,
  },
});

Pin + Scrub pattern

Hold an element fixed while the user scrolls through a section:

const tl = gsap.timeline({
  scrollTrigger: {
    trigger: ".story-section",
    start: "top top",
    end: "+=300%",
    pin: true,
    scrub: 1,
  },
});
tl.to(".step-1", { opacity: 1, y: 0 })
  .to(".step-1", { opacity: 0 })
  .to(".step-2", { opacity: 1, y: 0 })
  .to(".step-2", { opacity: 0 })
  .to(".step-3", { opacity: 1, y: 0 });

Workflow

1. Register plugins

import gsap from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
gsap.registerPlugin(ScrollTrigger);

2. Use gsap.context() for React cleanup

import { useRef, useLayoutEffect } from "react";

function AnimatedSection() {
  const containerRef = useRef<HTMLDivElement>(null);

  useLayoutEffect(() => {
    const ctx = gsap.context(() => {
      gsap.from(".reveal", {
        y: 60,
        opacity: 0,
        stagger: 0.1,
        scrollTrigger: {
          trigger: containerRef.current,
          start: "top 80%",
        },
      });
    }, containerRef);

    return () => ctx.revert();
  }, []);

  return <div ref={containerRef}>{/* children */}</div>;
}

3. Responsive ScrollTrigger with matchMedia

useLayoutEffect(() => {
  const ctx = gsap.context(() => {
    ScrollTrigger.matchMedia({
      "(min-width: 768px)": () => {
        gsap.to(".sidebar", {
          x: 0,
          scrollTrigger: { trigger: ".content", start: "top top", pin: true },
        });
      },
      "(max-width: 767px)": () => {
        gsap.set(".sidebar", { x: 0 });
      },
    });
  }, containerRef);
  return () => ctx.revert();
}, []);

4. Integrate Lenis for smooth scroll sync

import Lenis from "lenis";

useEffect(() => {
  const lenis = new Lenis();
  lenis.on("scroll", ScrollTrigger.update);
  gsap.ticker.add((time) => lenis.raf(time * 1000));
  gsap.ticker.lagSmoothing(0);

  return () => {
    gsap.ticker.remove(lenis.raf);
    lenis.destroy();
  };
}, []);

5. Performance budgets

• Keep total active ScrollTrigger instances under 20 per page
• Animate transform and opacity — avoid animating width, height, top, left
• Use will-change: transform sparingly and remove it after animation completes
• Test on mobile with real devices — not just DevTools throttling

Examples

Example 1 — Text reveal on scroll

useLayoutEffect(() => {
  const ctx = gsap.context(() => {
    gsap.utils.toArray<HTMLElement>(".split-line").forEach((line) => {
      gsap.from(line, {
        y: "100%",
        opacity: 0,
        duration: 0.8,
        ease: "power3.out",
        scrollTrigger: { trigger: line, start: "top 90%" },
      });
    });
  }, containerRef);
  return () => ctx.revert();
}, []);

Example 2 — Horizontal scroll section

useLayoutEffect(() => {
  const ctx = gsap.context(() => {
    const panels = gsap.utils.toArray<HTMLElement>(".panel");
    gsap.to(panels, {
      xPercent: -100 * (panels.length - 1),
      ease: "none",
      scrollTrigger: {
        trigger: ".horizontal-container",
        pin: true,
        scrub: 1,
        end: () => "+=" + document.querySelector(".horizontal-container")!.scrollWidth,
      },
    });
  }, containerRef);
  return () => ctx.revert();
}, []);

Example 3 — Counter animation

useLayoutEffect(() => {
  const ctx = gsap.context(() => {
    const counter = { value: 0 };
    gsap.to(counter, {
      value: 10000,
      duration: 2,
      ease: "power1.out",
      scrollTrigger: { trigger: ".counter-section", start: "top 75%" },
      onUpdate: () => {
        document.querySelector(".counter")!.textContent =
          Math.round(counter.value).toLocaleString();
      },
    });
  }, containerRef);
  return () => ctx.revert();
}, []);

Decision tree

• Scroll-triggered reveal (no pinning)? → gsap.from() with ScrollTrigger, start: "top 80%"
• Pinned section with progressive steps? → Timeline + ScrollTrigger with pin: true, scrub: 1
• Parallax background? → gsap.to() with ScrollTrigger, scrub: true
• Horizontal scroll section? → xPercent tween with pin: true and dynamic end
• Component enter/exit? → NOT GSAP — use Motion
• Smooth scroll across the page? → Lenis + ScrollTrigger sync
• Responsive breakpoints? → ScrollTrigger.matchMedia()

Edge cases and gotchas

1. React cleanup is mandatory — Failing to ctx.revert() causes memory leaks and zombie ScrollTrigger instances. Always use gsap.context() with useLayoutEffect.
2. Lenis on content-heavy pages — Lenis overrides native scroll behavior. On documentation sites or long-form content, this hurts usability. Only use Lenis when smooth scroll is integral to the design concept.
3. Pin spacing — Pinning adds extra height to the page flow. If layout breaks, check pinSpacing: false or account for the added space.
4. Touch devices — Scrub-heavy sections feel different on touch. Test swipe velocity and consider simplifying the experience on mobile.
5. Hot module replacement — GSAP instances survive HMR in development. If animations double, ensure cleanup runs on HMR updates.
6. GSAP license — GSAP is free for most use. The "No Charge" license covers nearly all scenarios. The Business Green license is needed for tools that let customers build animations.

Evaluation criteria

• gsap.registerPlugin(ScrollTrigger) called before any ScrollTrigger use
• All GSAP code wrapped in gsap.context() with cleanup in useLayoutEffect return
• Every pinned section justifies the scroll pause with meaningful content
• Touch/mobile scroll behavior tested on real devices
• Lenis used only when smooth scroll is integral to the concept (not on docs/dashboards)
• Total active ScrollTrigger instances per page are under 20
• Responsive behavior handled with ScrollTrigger.matchMedia()
• Animations target transform and opacity (not layout-triggering properties)