hyperframes/skills/gsap/references/scrolltrigger.md

ScrollTrigger

Registering

gsap.registerPlugin(ScrollTrigger);

Basic Trigger

gsap.to(".box", {
  x: 500,
  scrollTrigger: {
    trigger: ".box",
    start: "top center",
    end: "bottom center",
    toggleActions: "play reverse play reverse",
  },
});

start/end format: "triggerPosition viewportPosition". Examples: "top top", "center center", "bottom 80%", numeric px 500, relative "+=300", "+=100%" (scroller height), "max". Wrap in clamp() (v3.12+): "clamp(top bottom)". Can be a function returning string/number.

Key Config Options

Property	Type	Description
trigger	String/Element	Element whose position defines start. Required.
start	String/Number/Function	When active. Default "top bottom" (or "top top" if pinned).
end	String/Number/Function	When ends. Default "bottom top".
endTrigger	String/Element	Different element for end calculation.
scrub	Boolean/Number	Link progress to scroll. true = direct; number = catch-up seconds.
toggleActions	String	Four actions: onEnter, onLeave, onEnterBack, onLeaveBack. Values: play/pause/resume/reset/restart/complete/reverse/none. Default "play none none none".
pin	Boolean/String/Element	Pin element while active. true = pin trigger. Animate children, not the pinned element.
pinSpacing	Boolean/String	Default true (adds spacer). false or "margin".
horizontal	Boolean	For horizontal scrolling.
scroller	String/Element	Scroll container (default: viewport).
markers	Boolean/Object	Dev markers. Remove in production.
once	Boolean	Kill after end reached once.
snap	Number/Array/Function/"labels"/Object	Snap to progress values.
containerAnimation	Tween/Timeline	For fake horizontal scroll (see below).
toggleClass	String/Object	Add/remove class when active.
onEnter/onLeave/onEnterBack/onLeaveBack	Function	Callbacks; receive ScrollTrigger instance.
onUpdate/onToggle/onRefresh/onScrubComplete	Function	Progress/state callbacks.

Standalone (no linked tween): ScrollTrigger.create({...}) with callbacks.

Scrub

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

scrub: true = direct link; number (e.g. 1) = smooth lag.

Pinning

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

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 });

ScrollTrigger.batch()

Creates one ScrollTrigger per target, batches callbacks within a short interval. Good for staggered reveal of many elements.

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

Options: interval (batch window), batchMax (max per batch). Callbacks receive (targets, scrollTriggers).

Horizontal Scroll (containerAnimation)

Pin a section, animate inner content's x/xPercent horizontally on vertical scroll:

1. Pin the section
2. Animate inner content with ease: "none" (required)
3. Attach ScrollTrigger with pin + scrub
4. Use containerAnimation on nested triggers

const scrollTween = gsap.to(scrollingEl, {
  xPercent: () => Math.max(0, window.innerWidth - scrollingEl.offsetWidth),
  ease: "none",
  scrollTrigger: {
    trigger: scrollingEl,
    pin: scrollingEl.parentNode,
    start: "top top",
    end: "+=1000",
  },
});

gsap.to(".nested", {
  y: 100,
  scrollTrigger: { containerAnimation: scrollTween, trigger: ".wrapper", start: "left center" },
});

Pinning and snapping unavailable on containerAnimation-based ScrollTriggers.

ScrollTrigger.scrollerProxy()

Override scroll position reading for third-party smooth-scroll libraries. Call ScrollTrigger.update when the scroller updates.

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);

Refresh and Cleanup

• ScrollTrigger.refresh() — recalculate after DOM/layout changes. Auto on resize (200ms debounce).
• Create ScrollTriggers top-to-bottom or set refreshPriority.
• Kill instances when removing elements: ScrollTrigger.getAll().forEach(t => t.kill()) or ScrollTrigger.getById("id")?.kill().

Do Not

• Put ScrollTrigger on child tweens inside a timeline — put on the timeline.
• Nest ScrollTriggered animations inside a parent timeline.
• Use scrub and toggleActions together (scrub wins).
• Use an ease other than "none" on the horizontal animation with containerAnimation.
• Leave markers in production.
• Create triggers in random order without refreshPriority.
• Forget refresh() after layout changes.