DEV Community

Cover image for Mastering GSAP ScrollTrigger — A Complete Practical Guide
Vishwark
Vishwark

Posted on

Mastering GSAP ScrollTrigger — A Complete Practical Guide

#animation #gsap #motion #frontend

Scroll-based animations have become a core part of modern web experiences. From subtle reveal animations to immersive scroll-driven storytelling, GSAP ScrollTrigger is one of the most powerful tools to achieve this.

In this article, we’ll deeply understand what ScrollTrigger is, how it works, its core configurations, and the most commonly used effects in real-world projects.

🚀 What is ScrollTrigger?

ScrollTrigger connects scroll position with animation state.

In simple terms:

  • Scroll starts an animation
  • Scroll controls animation progress
  • Scroll pins, scrubs, or reverses animations

Think of the scrollbar as a timeline controller.

🧠 Core Mental Model

Every ScrollTrigger works around three concepts:

  1. Trigger – Which element controls the scroll logic
  2. Start – When animation starts
  3. End – When animation ends 
ScrollTrigger.create({
  trigger: ".section",
  start: "top center",
  end: "bottom top",
});
Enter fullscreen mode Exit fullscreen mode

ScrollTrigger defines a scroll range between start and end.

📍 Understanding start & end

The format is:

"<trigger-position> <viewport-position>"
Enter fullscreen mode Exit fullscreen mode

Examples:

  • "top bottom" → element enters viewport
  • "top center" → element top reaches viewport center
  • "center center" → element centered in viewport
  • "+=500" → 500px after start

🧩 Two Ways to Use ScrollTrigger

1️⃣ Triggering an animation (most common) 

gsap.from(".box", {
  y: 80,
  opacity: 0,
  scrollTrigger: {
    trigger: ".box",
    start: "top 80%",
  }
});
Enter fullscreen mode Exit fullscreen mode

✔ Runs once when the element enters view.

2️⃣ Scrub-based animation (scroll controls progress) 

gsap.to(".box", {
  x: 300,
  scrollTrigger: {
    trigger: ".section",
    start: "top center",
    end: "bottom center",
    scrub: true,
  }
});
Enter fullscreen mode Exit fullscreen mode

✔ Scrolling forward plays animation
✔ Scrolling backward reverses it

⚙️ Most Important ScrollTrigger Configs

✅ scrub

Syncs animation progress with scroll.

scrub: true   // exact sync
scrub: 1      // smooth delay
Enter fullscreen mode Exit fullscreen mode

Used for:

  • Parallax
  • Storytelling
  • Horizontal scroll

✅ pin

Pins an element during scroll.

pin: true
Enter fullscreen mode Exit fullscreen mode

Used for:

  • Hero sections
  • Scroll narratives
  • Feature walkthroughs

✅ markers (debugging) 

markers: true
Enter fullscreen mode Exit fullscreen mode

Shows start/end positions visually.
👉 Extremely helpful while learning.

✅ toggleActions 

toggleActions: "play pause resume reverse"
Enter fullscreen mode Exit fullscreen mode

Order:

onEnter → onLeave → onEnterBack → onLeaveBack
Enter fullscreen mode Exit fullscreen mode

Common patterns:

  • "play none none none" → play once
  • "play reverse play reverse" → bi-directional

✅ once 

once: true
Enter fullscreen mode Exit fullscreen mode

Animation plays once and never reverses.

✅ invalidateOnRefresh 

invalidateOnRefresh: true
Enter fullscreen mode Exit fullscreen mode

Recalculates positions on resize or orientation change.
✔ Recommended for responsive layouts.

⏳ ScrollTrigger + Timeline (Real Power)

Timelines allow scroll-based storytelling.

const tl = gsap.timeline({
  scrollTrigger: {
    trigger: ".section",
    start: "top top",
    end: "+=1000",
    scrub: true,
    pin: true,
  }
});

tl
  .to(".title", { opacity: 1, y: 0 })
  .to(".image", { scale: 1.2 })
  .to(".text", { opacity: 1 });
Enter fullscreen mode Exit fullscreen mode

✔ Each scroll section reveals part of the story.

🎨 Common Effects Built with ScrollTrigger

1️⃣ Reveal Animations 

gsap.from(".item", {
  y: 50,
  opacity: 0,
  scrollTrigger: {
    trigger: ".item",
    start: "top 85%",
  }
});
Enter fullscreen mode Exit fullscreen mode

2️⃣ Parallax Effect 

gsap.to(".bg", {
  yPercent: -20,
  scrollTrigger: {
    trigger: ".section",
    scrub: true,
  }
});
Enter fullscreen mode Exit fullscreen mode

Creates depth and motion illusion.

3️⃣ Pin + Scroll Storytelling 

scrollTrigger: {
  trigger: ".section",
  start: "top top",
  end: "+=200%",
  pin: true,
  scrub: true,
}
Enter fullscreen mode Exit fullscreen mode

4️⃣ Horizontal Scroll (Very Popular) 

gsap.to(".wrapper", {
  xPercent: -100,
  scrollTrigger: {
    trigger: ".container",
    pin: true,
    scrub: true,
    end: "+=1000",
  }
});
Enter fullscreen mode Exit fullscreen mode

Vertical scroll → horizontal movement.

5️⃣ Scroll Progress Tracking 

scrollTrigger: {
  onUpdate: self => {
    console.log(self.progress);
  }
}
Enter fullscreen mode Exit fullscreen mode

Used for:

  • Progress bars
  • Active section indicators

🔁 ScrollTrigger Lifecycle Callbacks 

scrollTrigger: {
  onEnter: () => {},
  onLeave: () => {},
  onEnterBack: () => {},
  onLeaveBack: () => {},
}
Enter fullscreen mode Exit fullscreen mode

Useful for:

  • Updating navigation state
  • Triggering side effects
  • Analytics

⚛️ Using ScrollTrigger with React (Best Practice) 

const sectionRef = useRef(null);

useLayoutEffect(() => {
  const ctx = gsap.context(() => {
    gsap.to(".box", {
      scrollTrigger: {
        trigger: sectionRef.current,
        scrub: true,
      }
    });
  }, sectionRef);

  return () => ctx.revert();
}, []);
Enter fullscreen mode Exit fullscreen mode

✔ Scoped animations
✔ Proper cleanup
✔ No memory leaks

🆚 ScrollTrigger vs Framer Motion

Use case Best tool
Simple reveals Framer Motion
Complex scroll animations GSAP
Pinning sections GSAP
Horizontal scroll GSAP
Gesture-based physics Framer Motion

🧭 How to Practice ScrollTrigger

  1. Enable markers
  2. Master start & end
  3. Experiment with scrub
  4. Add pin
  5. Build timeline-based sections
  6. Try horizontal scroll layouts

🎯 Final Thoughts

GSAP ScrollTrigger is not just an animation library — it’s a scroll interaction engine.

Once you understand:

  • start/end positioning
  • scrubbing
  • pinning
  • timelines

You can build high-end, production-grade scroll experiences with full control and performance.

Happy animating 🚀

Top comments (0)