GSAP ScrollTrigger Scrub: Control Animation with Scroll

In Blog #15, start and end defined an active scroll range. Without scrub, reaching the start activates a tween that continues according to time. Add scrub, and the scrollbar becomes the playhead.

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

What you will learn

1. What is ScrollTrigger scrub?

Scrub links animation progress to ScrollTrigger progress. Around 25% through the range, the animation is around 25% through its progress; the same mental model applies at 50%, 75% and 100%.

2. Normal ScrollTrigger versus scrub

3. Basic scrub: true

trigger chooses the controlling section, start opens the range, end closes it, and scrub links the animation playhead to that range.

scrollTrigger: {
  trigger: ".basic-scrub-demo",
  start: "top 80%",
  end: "bottom 20%",
  scrub: true
}

4. First scrub demo

5. Scroll down and scroll up

6. Start and end become the ruler

With scrub, the distance between start and end is the scroll-space ruler across which the animation is distributed.

7. Short versus long range

8. Interactive scrub range lab

9. Numeric scrub

A number such as scrub: 1 keeps scroll progress in control but lets the animation playhead catch up smoothly. It does not mean the scrubbed animation simply has a one-second duration.

10. scrub: true versus scrub: 1

11. Scrub smoothing playground

12. Scrub and duration

For a single scrubbed tween, scroll progress drives the overall motion. Inside a timeline, duration values remain meaningful because they determine how much of the timeline each tween occupies.

13. Scrub and easing

ease: "none" produces a linear property mapping. An ease such as power2.out redistributes the property change across progress; scrub is still in control.

14. Scrub with gsap.to()

gsap.to(card, {
  x: getDistance,
  rotation: 10,
  scale: 1.05,
  ease: "none",
  scrollTrigger: {
    trigger: demo,
    start: "top 80%",
    end: "bottom 20%",
    scrub: true,
    invalidateOnRefresh: true
  }
});

The current visual state becomes progress zero; the declared target state becomes progress one.

15. Scrub with gsap.fromTo()

gsap.fromTo(card,
  { xPercent: -20, opacity: 0.35, scale: 0.9 },
  { xPercent: 0, opacity: 1, scale: 1, ease: "none",
    scrollTrigger: { trigger: demo, start: "top 80%",
      end: "bottom 30%", scrub: true }
  }
);

fromTo() is useful when both endpoints need to be explicit.

16. Scrub a timeline

const tl = gsap.timeline({
  scrollTrigger: { trigger: section, start: "top 80%",
    end: "bottom 20%", scrub: true }
});

tl.from(label, { opacity: 0, y: 20 })
  .from(title, { opacity: 0, y: 50 }, "-=0.2")
  .from(cards, { opacity: 0, y: 30, stagger: 0.1 }, "-=0.2");

17. Timeline duration ratios

18. Scrub plus stagger

ScrollTrigger controls overall progress. Stagger distributes timing between targets inside that progress.

19. Live ScrollTrigger progress

20. Moving object along a safe track

const getDistance = () =>
  Math.max(0, track.clientWidth - box.offsetWidth);

gsap.to(box, {
  x: getDistance,
  ease: "none",
  scrollTrigger: { trigger: demo, scrub: true,
    invalidateOnRefresh: true }
});

21. Responsive travel distance

A fixed x: 1000 can escape its container on a phone. Measuring the track creates a safe endpoint and invalidateOnRefresh: true lets ScrollTrigger recalculate it after responsive layout changes.

22. Scale and rotation with scroll

Decorative motion can rotate; reading content should stay calm and legible.

23. Image reveal with scrub

The image scales from 1.08 to 1 while a subtle vertical shift settles into place.

24. A simple parallax-like effect

Two decorative layers move by different small amounts. Native page scrolling remains untouched.

25. Multiple properties

A single scrubbed tween can map x, y, rotation, scale and borderRadius together. Keep the effect purposeful and transform-heavy.

26. Scrub does not mean pin

Moving an element horizontally also does not create a horizontal-scrolling site. This tutorial clips tracks and never intercepts wheel or touch scrolling.

27. Practical hero-like scrub

28. Practical services scrub

29. Practical process sequence

A transform-based progress line fills while each step enters its portion of the timeline. Scrolling upward reverses the story.

30. Numeric scrub mental model

Direct scrub suits precise indicators and tracks. Numeric scrub can soften image motion, text decoration and storytelling; too much smoothing may feel disconnected.

31. GSAP ScrollTrigger Scrub Lab

32. Safe rebuild architecture

function destroyLab() {
  if (!labAnimation) return;
  if (labAnimation.scrollTrigger) labAnimation.scrollTrigger.kill();
  labAnimation.kill();
  labAnimation = null;
}

The controls kill only the lab-owned timeline and its trigger, reset only lab properties, and rebuild. They never call ScrollTrigger.getAll().

33. Common scrub mistakes

34. Performance

Prefer transforms and opacity, use transform-based progress bars, keep DOM updates lightweight, and avoid repeated layout reads inside onUpdate. Test the full page because several individually smooth effects can still compete when they overlap.

35. Accessibility and mobile

Essential content is visible in the HTML before JavaScript runs. The script respects prefers-reduced-motion, keeps native scrolling, shortens nothing into an unreadable state, and uses real buttons with aria-pressed. Tracks clip locally at 320px rather than creating page-level overflow.

36. Mini challenge

gsap.to(box, {
  x: () => Math.max(0, track.clientWidth - box.offsetWidth),
  ease: "none",
  scrollTrigger: {
    trigger: challenge,
    start: "top 80%",
    end: "bottom 20%",
    scrub: true,
    invalidateOnRefresh: true,
    onUpdate: self => gsap.set(progressBar, { scaleX: self.progress })
  }
});

37. Quick reference

38. Scrub cheat sheet

39. Final mental model

40. Preview Blog #17

Scrub connects animation to scrolling. The next lesson will introduce pin, which can keep a section fixed while its scroll-driven sequence progresses. Blog #17 is not linked until it exists.

ScrollTrigger.create({
  trigger: ".pin-section",
  start: "top top",
  end: "+=1000",
  pin: true
});

Continue the GSAP series

Review GSAP stagger, GSAP easing, timelines, timeline position parameters, timeline + stagger, the ScrollTrigger tutorial, and ScrollTrigger start and end.