Everything You Need to Know About GSAP ScrollTrigger

GSAP (GreenSock Animation Platform) is a powerful JavaScript library for creating high-performance animations, and its ScrollTrigger plugin takes it to the next level by enabling scroll-based animations with precise control. ScrollTrigger allows developers to create engaging, interactive experiences that respond to the user's scroll position. This blog dives into everything you need to know about ScrollTrigger, including its core features, configuration options, and practical examples.

What is ScrollTrigger?

ScrollTrigger is a free plugin for GSAP that lets you trigger animations based on the scroll position of an element or the viewport. It’s highly customizable, supporting features like pinning, scrubbing, snapping, and toggle actions, making it ideal for creating immersive web experiences. Whether you’re animating elements as they enter the viewport or building complex scroll-driven interactions, ScrollTrigger provides the tools to make it happen seamlessly.

To use ScrollTrigger, you need to include the GSAP core library and the ScrollTrigger plugin in your project:

<script src="<https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js>"></script>
<script src="<https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/ScrollTrigger.min.js>"></script>

Then, register the plugin:

gsap.registerPlugin(ScrollTrigger);

Core Concepts of ScrollTrigger

ScrollTrigger works by associating animations with the scroll position of a trigger element relative to a scroller (usually the viewport). Here’s a breakdown of its key configuration options, based on the provided settings:

1. Trigger

The trigger property defines the element (or selector) that ScrollTrigger watches to determine scroll positions.

• Example: trigger: ".selector" or trigger: document.querySelector(".my-element")
• The trigger element’s position relative to the scroller determines when the animation starts and ends.

2. Start and End

The start and end properties define when the animation begins and ends, respectively, using a combination of trigger and scroller positions.

• Syntax: "[trigger position] [scroller position]"
  • Trigger positions: top, center, bottom, or pixel/percentage values (e.g., 20px, 80%).
  • Scroller positions: top, center, bottom, or pixel/percentage values.
• Example: start: "top center" (animation starts when the top of the trigger hits the center of the viewport).
• Relative end: Use end: "+=500" to set the end 500 pixels after the start.

3. Scrub

The scrub property links the animation’s progress directly to the scroll position, creating a smooth “scrubbing” effect.

• Options:
  • true: Animation progresses smoothly with scroll.
  • Number (e.g., 1): Time in seconds for the animation to catch up to the scroll position.
• Example: scrub: true makes the animation follow the scroll exactly.

4. Pin

The pin property “pins” an element in place during scrolling, keeping it fixed until the ScrollTrigger ends.

• Options: true, a selector, or an element.
• Example: pin: ".selector" pins the specified element.
• Use pinSpacing: false to disable the default spacer div that maintains layout.
• Use pinReparent: true to move the pinned element to the documentElement during pinning for better compatibility.

5. Markers

The markers property adds visual markers to the page during development, showing the start and end positions.

• Example: markers: true
• Tip: Always disable markers in production to avoid cluttering the UI.

6. Toggle Actions

The toggleActions property controls how the animation behaves when the trigger enters, leaves, or re-enters the viewport.

• Options: play, pause, resume, reset, restart, complete, reverse, none.
• Syntax: "onEnter onLeave onEnterBack onLeaveBack"
• Example: toggleActions: "play pause resume reset"

7. Toggle Class

The toggleClass property adds or removes a CSS class based on scroll position.

• Example: toggleClass: "active" toggles the active class on the trigger element.

8. Fast Scroll End

The fastScrollEnd property forces the animation to complete quickly if the user scrolls past it rapidly.

• Options: true or a velocity number.
• Example: fastScrollEnd: true

9. Container Animation

The containerAnimation property allows ScrollTrigger to work with a horizontal scrolling animation (e.g., a GSAP tween).

• Example: containerAnimation: tween (where tween is a linear GSAP animation).

10. Snap

The snap property makes the scroll position “snap” to specific points, creating a smooth scrolling experience.

• Options:
  • Number (e.g., snapTo: 1 / 10): Snaps to increments of the animation’s progress.
  • "labels": Snaps to animation labels.
  • Function or Array: Custom snap points.
• Additional settings: duration, directional, ease, onComplete, onStart, onInterrupt.
• Example:
  Copy

  snap: {
    snapTo: 1 / 10,
    duration: 0.5,
    directional: true,
    ease: "power3"
  }

11. Callbacks

ScrollTrigger provides a range of callbacks to hook into various events:

• onEnter, onLeave, onEnterBack, onLeaveBack, onUpdate, onToggle, onRefresh, onRefreshInit, onScrubComplete.
• Example: onEnter: () => console.log("Entered viewport")

12. Additional Options

• id: "my-id": Assigns a unique identifier for debugging or referencing.
• anticipatePin: 1: Helps prevent jumps during pinning.
• pinType: "transform": Use "fixed" for CSS fixed positioning (if supported).
• pinnedContainer: ".selector": Specifies a container for pinned elements.
• preventOverlaps: true: Ensures ScrollTriggers don’t overlap (or use a custom string).
• once: true: Destroys the ScrollTrigger after it runs once.
• endTrigger: ".selector": Uses a different element to determine the end position.
• horizontal: true: Switches to horizontal scrolling mode.
• invalidateOnRefresh: true: Recalculates start/end positions on refresh.
• refreshPriority: 1: Sets the order for refreshing multiple ScrollTriggers.

Practical Example

Here’s a complete example of a ScrollTrigger animation that fades in a box and pins it while scrolling:

gsap.to(".box", {
  opacity: 1,
  y: 100,
  duration: 1,
  scrollTrigger: {
    trigger: ".box",
    start: "top 80%",
    end: "+=300",
    scrub: true,
    pin: true,
    markers: true,
    toggleActions: "play pause resume reset",
    onEnter: () => console.log("Box entered viewport"),
    onUpdate: (self) => console.log("Progress:", self.progress)
  }
});

Explanation:

• The .box element fades in and moves 100px down over 1 second.
• The animation starts when the top of .box is 80% from the top of the viewport.
• The animation ends 300px after the start.
• scrub: true ties the animation to the scroll position.
• pin: true keeps the box fixed during the animation.
• markers: true shows start/end points for debugging.
• Callbacks log events to the console.

Best Practices

1. Optimize Performance: Use will-change: transform in CSS for animated elements to improve rendering.
2. Responsive Design: Use invalidateOnRefresh: true to recalculate positions on window resize.
3. Debugging: Enable markers: true during development, but remove them in production.
4. Combine with GSAP: Leverage GSAP’s timelines, eases, and other features for complex animations.
5. Test Extensively: Test on various devices and browsers, as scroll behavior can vary.

Common Use Cases

• Parallax Effects: Create smooth background movements with scrub.
• Section Pinning: Pin headers or sections for storytelling.
• Scroll-Based Reveals: Fade in elements as they enter the viewport.
• Horizontal Scrolling: Use horizontal: true for gallery-style layouts.
• Snapping Sections: Use snap for controlled scroll stops.

Conclusion

GSAP ScrollTrigger is a game-changer for scroll-based animations, offering unmatched flexibility and control. Its extensive configuration options allow you to create everything from simple fade-ins to complex, scroll-driven experiences. By mastering its features like pinning, scrubbing, and snapping, you can elevate your web projects to new heights. Experiment with the provided settings, and check out the GSAP documentation for more inspiration!