Scrollcraft
Chapter 7 of 15RO

GSAP: timelines, scrub and pin.

When a scene has several moving parts that must stay in step with the scroll, GSAP and its ScrollTrigger plugin do the bookkeeping. Every technique below runs live beside its code.

Chapter 7 of 154 min read

What you will learn

By the end of this chapter
  1. 01Sequence several movements with a GSAP timeline and its position parameter.
  2. 02Tie a timeline to the scroll with ScrollTrigger: scrub, pin and start and end points.
  3. 03Draw SVG lines and reveal split text with the free GSAP plugins.
  4. 04Clean up in React with useGSAP, and respect reduced motion with gsap.matchMedia().

01 · Set it up

Free, including every plugin
a

Install

GSAP and all its plugins, including ScrollTrigger, SplitText and DrawSVG, have been free for commercial use since 2025. With a bundler, install it from npm. On a plain page, load the files from a CDN, in this order: GSAP first, then each plugin.

bash
npm install gsap
b

Share one clock with Lenis

Smooth scrolling and ScrollTrigger must agree on where the page is. Let Lenis report each scroll to ScrollTrigger, and drive Lenis from the GSAP ticker so both move on the same frame.

html
<script src="https://cdn.jsdelivr.net/npm/gsap@3.15.1/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.15.1/dist/ScrollTrigger.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/lenis@1.3.27/dist/lenis.min.js"></script>
<script>
  gsap.registerPlugin(ScrollTrigger);

  // Lenis and ScrollTrigger share one clock.
  const lenis = new Lenis({ lerp: 0.1 });
  lenis.on('scroll', ScrollTrigger.update);
  gsap.ticker.add((time) => lenis.raf(time * 1000));
  gsap.ticker.lagSmoothing(0);
</script>

Without the shared ticker the pinned sections drift by a frame and visibly shake.

02 · Five techniques, live

Scroll inside each preview
1

Timeline

A timeline plays steps in order. The position parameter makes them overlap, so three small moves read as one entrance.

Use -=0.6 to start before the previous step ends and <0.2 to start just after it began.

HTML
<script src="https://cdn.jsdelivr.net/npm/gsap@3.15.1/dist/gsap.min.js"></script>
<section class="hero">
  <h1>
    <span class="ln"><span>Sound that</span></span>
    <span class="ln"><span>fills the room.</span></span>
  </h1>
  <p class="sub">A small speaker that plays in every direction.</p>
  <a class="cta" href="#">Pre-order</a>
</section>
2

Scrub

With scrub, the scroll position becomes the playhead: scrolling down plays the timeline, scrolling up rewinds it.

A number such as scrub: 0.6 lets the playhead catch up over 0.6 seconds, which smooths a jerky wheel.

HTML
<script src="https://cdn.jsdelivr.net/npm/gsap@3.15.1/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.15.1/dist/ScrollTrigger.min.js"></script>
<section class="stage">
  <div class="frame"><div class="box"></div></div>
</section>
<p class="after">The timeline follows the scroll, both ways.</p>
3

Pin

Pinning holds a section in place while the reader keeps scrolling, and gives the timeline that distance to play in.

Set end: '+=200%' to pin for twice the screen height. Pin one section at a time, and never inside a transformed parent.

HTML
<script src="https://cdn.jsdelivr.net/npm/gsap@3.15.1/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.15.1/dist/ScrollTrigger.min.js"></script>
<p class="lead">Scroll down.</p>
<section class="pin">
  <div class="bar"><i></i></div>
  <article><h2>Listen</h2><p>A week of questions before any sketch.</p></article>
  <article><h2>Reduce</h2><p>One idea, said as plainly as possible.</p></article>
  <article><h2>Move</h2><p>Motion rules, so the brand behaves the same everywhere.</p></article>
</section>
<p class="lead">The section let go.</p>
4

Draw an SVG line

DrawSVG animates how much of a stroke is visible. Tied to a scrubbed trigger, a route or signature draws itself as the reader moves.

getPointAtLength gives the end of the drawn line, so a marker can ride along it.

HTML
<script src="https://cdn.jsdelivr.net/npm/gsap@3.15.1/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.15.1/dist/ScrollTrigger.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.15.1/dist/DrawSVGPlugin.min.js"></script>
<section class="stage">
  <div class="frame">
    <svg viewBox="0 0 300 200" aria-hidden="true">
      <path class="ghost" d="M20 170 C 70 20, 120 20, 150 100 S 230 180, 280 30" />
      <path class="line" d="M20 170 C 70 20, 120 20, 150 100 S 230 180, 280 30" />
      <circle class="dot" r="5" cx="20" cy="170" />
    </svg>
  </div>
</section>
<p class="after">DrawSVG draws the stroke; the dot rides along the same path.</p>
5

Split text into lines

SplitText finds the real line breaks after the fonts load, wraps each line in a mask and lets you animate them one after another.

autoSplit: true splits again when the width changes, and returning the animation from onSplit lets GSAP clean up the old one.

HTML
<script src="https://cdn.jsdelivr.net/npm/gsap@3.15.1/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.15.1/dist/ScrollTrigger.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.15.1/dist/SplitText.min.js"></script>
<p class="lead">Scroll down.</p>
<h2 class="title">Quiet pages that move only when it matters, and say one thing at a time.</h2>
<p class="lead"></p>

03 · In React and Next.js

useGSAP
a

Clean up on unmount

The useGSAP hook from @gsap/react scopes every selector to one component and reverts every animation and trigger when it unmounts, so client-side navigation leaves nothing behind.

tsx
// components/Reveal.tsx
'use client';
import { useRef, type ReactNode } from 'react';
import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
import { useGSAP } from '@gsap/react';

gsap.registerPlugin(useGSAP, ScrollTrigger);

export default function Reveal({ children }: { children: ReactNode }) {
  const root = useRef<HTMLDivElement>(null);

  // Everything created inside is scoped to root and reverted on unmount.
  useGSAP(() => {
    const mm = gsap.matchMedia();
    mm.add('(prefers-reduced-motion: no-preference)', () => {
      gsap.from('.reveal', {
        y: 28, opacity: 0, duration: 0.9, ease: 'power3.out', stagger: 0.08,
        scrollTrigger: { trigger: root.current, start: 'top 80%', once: true },
      });
    });
  }, { scope: root });

  return <div ref={root}>{children}</div>;
}
b

Respect reduced motion with matchMedia

gsap.matchMedia() builds animations only while a media query matches and undoes them when it stops matching. Every preview in this chapter wraps its scroll animations in (prefers-reduced-motion: no-preference).

04 · CSS scroll timelines

Less JavaScript, check support

CSS can now tie an animation to scroll with animation-timeline. The WebKit blog describes support in a Safari 26 beta. Check the current table on caniuse.com for Chrome and Firefox, and keep a fallback.

css
@keyframes rise {
  from { opacity: 0; transform: translateY(28px); }
  to   { opacity: 1; transform: none; }
}

/* Only where the browser understands scroll timelines. */
@supports (animation-timeline: view()) {
  .reveal {
    animation: rise linear both;
    animation-timeline: view();
    animation-range: entry 0% entry 60%;
  }
  .progress {
    transform-origin: 0 50%;
    animation: grow linear both;
    animation-timeline: scroll(root);
  }
}
@keyframes grow { from { transform: scaleX(0); } to { transform: scaleX(1); } }
js
const native = CSS.supports('animation-timeline: view()');
if (!native) {
  // fall back to IntersectionObserver reveals, as in the example site
}

One trade-off: a view timeline scrubs both ways, so content fades out again when you scroll back up. The IntersectionObserver version in the example keeps it visible. Pick the behaviour you want.

05 · When to reach for GSAP

a

Stay with plain code

One reveal, one progress bar or one parallax layer. The Motion chapter does each in a few lines, with nothing to download.

b

Use GSAP

Several elements that must move in a fixed order, a pinned scene, scrubbing that has to rewind exactly, text split by real line breaks, or SVG drawing.

c

Use both

Most production sites mix them: CSS and IntersectionObserver for the small reveals, GSAP for the two or three scenes that carry the story.

Practice · Work with AI

The same task in your tool

GSAP code goes wrong in predictable ways: missing plugin registration, triggers measured too early, no cleanup. Name those in the prompt.

Open a terminal in the project folder and run claude. Press Shift+Tab until plan mode is on, paste the prompt, read the plan, then approve it. Project rules go in CLAUDE.md.

A pinned scene

Prompt
Read CLAUDE.md. Add a pinned scene to the site for [subject] with GSAP 3.15.1 and ScrollTrigger from jsDelivr: the section stays pinned for 200% of the screen height while three steps hand over one after another, with a progress line. Register the plugin, build it inside gsap.matchMedia so nothing animates under prefers-reduced-motion (the steps stack instead), and call ScrollTrigger.refresh() after images load. Show me the plan first.

Check the triggers

Prompt
Turn on ScrollTrigger markers temporarily and tell me where each trigger starts and ends at 375 and 1440 pixels wide. Then remove the markers. Do not change anything else.

Practice · Exercises

Try first, then compare
1

Read the position parameter

In tl.to(a, {…}).to(b, {…}, "-=0.4").to(c, {…}, "<"), when does each tween start?

Hint: “<” refers to the start of the previous tween.

Show the solution

a starts at 0. b starts 0.4 seconds before a ends. c starts at the same moment as b.

2

Scrub or play

For a headline that appears once, and for a product that rotates as you scroll, choose between scrub and toggleActions.

Hint: does the animation follow the scroll both ways?

Show the solution

The headline plays once with toggleActions: "play none none none" (or once: true). The rotating product uses scrub, so it moves forward and back exactly with the scroll.

3

Clean up in React

A component creates a ScrollTrigger in useEffect without cleanup. What happens after navigating away and back three times?

Hint: nothing removes the old triggers.

Show the solution

Four sets of triggers exist, three attached to elements that are gone, so positions are wrong and work is wasted. Use useGSAP with a scope, which reverts everything on unmount.

tsx
useGSAP(() => {
  gsap.from('.reveal', { y: 28, opacity: 0, scrollTrigger: { trigger: root.current, start: 'top 80%' } });
}, { scope: root });

Practice · Course project

One site, built across the course

Give the site for [subject] one scene that only GSAP makes easy: a pinned sequence that tells part of the story.

  1. Choose the part of the story that has three beats, and write them in notes.md.
  2. Run “A pinned scene” and check it at three widths.
  3. Run “Check the triggers” and adjust start and end if a step arrives too early or too late.
  4. Commit, with the GSAP version pinned in the script URL.

Practice · Test it

Check the result
  • The section pins and unpins without a jump or a gap at 375, 768 and 1440 pixels.
  • Scrolling back up plays the scene backwards exactly.
  • With reduced motion on, nothing is pinned and the three steps read as a list.
  • The Console shows no warnings about missing plugins or targets.

Practice · Assessment

Acceptance criteria

0 of 4 criteria met

Next WebGL

A three.js scene driven by scroll, particles moved on the GPU, a full-screen shader and a dissolve between two scenes.

Keyboard shortcuts: [ previous chapter · ] next chapter