gsap-scrolltrigger

Register the ScrollTrigger plugin with gsap.registerPlugin(ScrollTrigger), then add a scrollTrigger config object to your tween or timeline with trigger, start, and end properties. Use toggleActions for play/reverse behavior or scrub to link progress directly to scroll position.

Set pin: true in the scrollTrigger config and define an end value like "+=1000" to pin for 1000px of scroll. ScrollTrigger adds pin spacing by default so the layout does not collapse; animate children of the pinned element rather than the pinned element itself.

Use scrub when animation progress should follow scroll position directly, and toggleActions for discrete play/reverse behavior at trigger boundaries. Do not combine both on the same ScrollTrigger; if both are present, scrub wins.

Trigger positions are calculated at creation time, so dynamic content, images, or fonts that change layout make them stale. Call ScrollTrigger.refresh() after DOM or layout changes; viewport resize is handled automatically with a 200ms debounce.

Yes, but ScrollTrigger instances must be cleaned up when components unmount to avoid stale triggers. Use the useGSAP() hook from the @gsap/react package for automatic cleanup, or kill instances manually in a useEffect cleanup function.

Use ScrollTrigger.scrollerProxy() to override how ScrollTrigger reads and writes scroll position for your scroller, providing scrollTop getter/setter functions. Then register ScrollTrigger.update as a listener on the third-party scroller so positions stay synchronized.