This is a collection of notes (including a demo) about scrollytelling.

I am not an expert in scrollytelling - I'm learning alongside you. The purpose of these notes is not to prescribe the “correct” way, but to quickly introduce you to key scrollytelling concepts (like sticky positioning and scroll-based animation) that I’ve discovered through my own research. The techniques shown here reflect my current understanding and are intended as helpful recommendations, not definitive best practices.

Scrollytelling is a storytelling technique used by websites where content changes and animates in response to the user's scroll actions. As you scroll, a story unfolds, revealing new information, triggering animations, and smoothly transitioning between scenes - creating an interactive, immersive, narrative experience. Some websites that implement this art form extremely well include::

• Lenis
• GTA VI
• Getty

The necessary libraries and frameworks generally include:

• An animation framework such as Framer Motion or GSAP
• A smooth scroll library such as Lenis

In these notes, we're going to use GSAP + Lenis on top of React.

• Lenis makes scrolling buttery smooth while allowing for regular CSS transforms, unlike many other smooth scrolling solutions.
• The most important difference is that it preserves the ability to use position: sticky in CSS, which results in an amazing scrolling experience.
  • Many of the elements you see on Lenis’s own website use position: sticky.
• A good alternative for Lenis would be using GSAP's ScrollSmoother plugin because it makes things like parallax effects so much easier.
  • "Sticky positioning" will not work if you use ScrollSmoother instead of Lenis and you will have to rely on GSAP's "pin" property.
  • Lenis also makes the scrollbar appear completely smooth as well, which ScrollSmoother fails to do.
  • You can find the docs on ScrollSmoother here.

• GSAP is a comprehensive animation framework with lots of support for a variety of different animations, from basic animations to animating text and SVGs.
• GSAP includes a plugin called ScrollTrigger that provides a way to control animations based on scroll progress.
• It also includes a property called scrub which allows animations to play forward and backward with scroll, instead of just happening once.
  • Framer Motion does not include scrub, which lets users replay animations like it's a cinematic.
• I would highly recommend taking a look at GSAP's docs, especially the cheatsheet.

The ScrollTrigger plugin allows you to make amazing scroll-based animations and is obviously a necessity for scrollytelling.

import gsap from "gsap";

import { ReactLenis, useLenis } from "lenis/react";

import { ScrollTrigger } from "gsap/ScrollTrigger";

gsap.registerPlugin(ScrollTrigger);

You should sync Lenis’s animation frame loop with GSAP’s ticker so that animations and scroll smoothing happen on the same timing, on the same loop. This is the recommended way by Lenis.

import gsap from "gsap";

import { ReactLenis } from "lenis/react";

import { useEffect, useRef } from "react";


function App() {
   const lenisRef = useRef();

    useEffect(() =>gt; {
     function update(time) {
       lenisRef.current?.lenis?.raf(performance.now());
     }

      gsap.ticker.add(update);

      return () =>gt; gsap.ticker.remove(update);
   }, []);

    return (
     main>gt;
       ReactLenis root options={{ autoRaf: false }} ref={lenisRef} />gt;
       {/* Rest of Website */}
     main>gt;
   );

}