basementstudio / scrollytelling

A library for creating Scrollytelling animations, powered by React & GSAP.

BSMNT Scrollytelling

BSMNT Scrollytelling is a library for creating Scrollytelling animations. It's powered by GSAP ScrollTrigger, but abstracts away some things to make it work better with React.

---

👇 New documentation here! 👇

• 💡 Core Concepts
• 📕 API Reference

---

Installation

To get started, we'll need the @bsmnt/scrollytelling package, as well as the required peer dependency: GSAP.

yarn add @bsmnt/scrollytelling gsap

Why

At basement, we've built a bunch of websites that use scroll animations. Over the years, we faced some issues that required solutions that we copy-pased throughout different project. We decided to build a library to share how we build these with the world.

Challenges we faced

• Needed a deep understanding of how GSAP works with ScrollTrigger.
• Needed to be careful about running animations inside useEffect and then cleaning them up.
• Couldn’t think of scroll animations in terms of a start and an end, so it was hard to fire up animations at the exact scroll progress we needed to.

What

We aimed at componentizing a way of building scroll animations that could:

• ✅ Provide sensible defaults for scroll animations, such as scrub: true, and ease: 'linear'.
• ✅ Take care of component mounting and unmounting.
• ✅ Create animations with absolute positioning defined by a start and an end, instead of a time-based duration.

As an added benefit, going "component-based" allowed us to:

• ✅ Improve compatibility with React Server Components: our components definitely 'use client', but not necessarily the parents or children of our components.
• ✅ Compose animations at every level of the tree, as it all works with React Context.

A simple example of how this works:

Exports

• Root: Creates timeline and scrollTrigger, provides React Context.
• Animation: Appends an animation to the timeline. Receives a tween prop that will control how the animation behaves.
• Waypoint: Runs a callback or tween at a specific point in the timeline. Can also receive a label prop, that will create a GSAP label at that position.
• RegisterGsapPlugins: Registers custom GSAP plugins, if you need them for a specific use case.
• Parallax: Helper to create a simple parallax.
• ImageSequenceCanvas: Helper to create a simple image sequence animation.
• useScrollytelling: Context consumer. Returns the timeline.
• useScrollToLabel: Scrolls to the label name you pass. Labels can be added with the Waypoint component.

Demo

We did a small demo to showcase this library in action. This is the best place to see how the library works in a real world scenario. Check it out:

• Site URL: https://scrollytelling.basement.studio/
• Code: https://github.com/basementstudio/scrollytelling/blob/main/website/README.md

Examples

• Simple tweening: https://stackblitz.com/edit/react-ts-8rqm8k?file=App.tsx
• With Lenis Smooth Scroll: https://stackblitz.com/edit/react-ts-uuwfed?file=App.tsx
• Layered pinning: https://stackblitz.com/edit/react-ts-4dtlww?file=App.tsx
• Three.js Tube: https://codesandbox.io/s/978cns?file=/src/App.js

Troubleshooting

"My simple animation is not doing anything on scroll"

Please check your start and end values for your Root component. A typical issue comes when:

1. your animation "starts when the start of the scroller hits the start of the viewport",
2. your animation "ends when the bottom of the scroller hits the bottom of the viewport",
3. the element your Root wraps around is only 100vh tall, so the animation's duration is 0.

To fix this, either add more height to the element your Root wraps, or tweak the end value to be something like bottom start, which would mean "when the bottom of the scroller hits the start of the viewport".

---

GSAP files are subject to GreenSock's standard license which can be found at https://greensock.com/standard-license/

scrollytelling's Issues

Horizontal scrolling - issue

Hello everyone, could someone please explain if it is also possible to create horizontal scrooling?

I have created a horizontal scrooling with standard gsap, but I can't figure out how to do it on scrollytelling. Thank you.

Here is the code I am using with gsap without scrollytelling (next js, tailwind):

Add Debugger Concept to Core Concepts

fix: horizontal scroll example

The current horizontal scroll example from the pin section in the documentation (stackblitz link) has a problem when it comes to horizontal overflows.

Said problem can be seen in the following image where one can scroll horizontally and the animation is a vertical scrolling one:

The css class pin-style has overscroll-behavior: none but maybe this isn't properly applied.

[Feature Request] A better implementation of headless component

I am just sharing the idea of better implementation of the existing component. The way below we have more control of the value to the children div or components. Hence we no need to create extra state to save the progress value etc. The methods below can be found in many packages or headless components such as headless tailwind ui, rainbowkit

children({...props}) allow to pass any properties and value to the children directly.

import Link from 'next/link';

const NavLink = ({ children, href, activeClassName = '', ...props }) => {
  const router = useRouter();
  return (
    <Link href={href} {...props}>
      {children({ active: router.asPath === href })}
    </Link>
  );
};

The component below direct provide the value to its children components without creating extra state or create global state outside the component.

 <NavLink href="/card">
                  {({ active }) => {
                    return (
                      <span
                        className={classNames(
                          active
                            ? 'text-hampton-200 shadow-[#cfb286] [text-shadow:_0_1px_12px_var(--tw-shadow-color)]'
                            : 'text-hampton-200/30 hover:text-hampton-200/70 transition',
                        )}
                      >
                        Cards
                      </span>
                    );
                  }}
                </NavLink>

Current Behavior:

cost [progress,setProgress] = useState({value: 0})

    <Scrollytelling.Root
      // start="top top"
      // end="bottom bottom"
      scrub={1}
      debug={true}
    >
      <Scrollytelling.Animation
   tween={{
              start: 0,
              end: 100,
              target: progress,
              to: {
                value: 1,
                onUpdate: () => setProgress(progress.value),
              },
            }}
      >
          <div>
             // assume having a deep nested children
              <motion.div
              className="absolute inset-0 bg-gradient-to-b from-sky-50 to-sky-100 opacity-100"
              style={{ opacity: progress }}
            >
              Test opacity progress
            </motion.div>
          </div>
          );
        }}
      </Scrollytelling.Animation>
    </Scrollytelling.Root>

Expected Result:

    <Scrollytelling.Root
      // start="top top"
      // end="bottom bottom"
      scrub={1}
      debug={true}
    >
      <Scrollytelling.Animation
        tween={{
          start: 0,
          end: 55,
        }}
      >
        {({ progress, ...props }) => {
          return (
          <div>
             // assume i always need to pass the progress and props to deep nested children
              <motion.div
              {...props}
              className="absolute inset-0 bg-gradient-to-b from-sky-50 to-sky-100 opacity-100"
              style={{ opacity: progress }}
            >
              Test opacity progress
            </motion.div>
          </div>
          );
        }}
      </Scrollytelling.Animation>
    </Scrollytelling.Root>

Pins not working

Hi!

I used your example to get Pins working with next.js. As I got an error, that the "childHeight" prop is required, i replaced the number 0 with the string 0, which worked in the example sandbox (using version 0.2.7). However, it doesn't work in my local project (all containers just scroll as normal, without the stickyness).

Here's my page code:

import * as Scrollytelling from "@bsmnt/scrollytelling";

import "./style.css";

export default function Home() {

    return (
        <main>
            <Scrollytelling.Root>
                <Scrollytelling.Pin
                    childHeight={'0'}
                    pinSpacerHeight={'100vh'}
                    top={0}
                >
                    <section className="section">
                        <div className="wrapper">
                            <h1>Layered pinning 1</h1>
                        </div>
                    </section>
                </Scrollytelling.Pin>
            </Scrollytelling.Root>

            <Scrollytelling.Root>
                <Scrollytelling.Pin
                    childHeight={'0'}
                    pinSpacerHeight={'100vh'}
                    top={0}
                >
                    <section className="section orange">
                        <div className="wrapper">
                            <h1>Layered pinning 2</h1>
                        </div>
                    </section>
                </Scrollytelling.Pin>
            </Scrollytelling.Root>

            <Scrollytelling.Root>
                <Scrollytelling.Pin
                    childHeight={'0'}
                    pinSpacerHeight={'100vh'}
                    top={0}
                >
                    <section className="section">
                        <div className="wrapper">
                            <h1>Layered pinning 3</h1>
                        </div>
                    </section>
                </Scrollytelling.Pin>
            </Scrollytelling.Root>

            <Scrollytelling.Root>
                <Scrollytelling.Pin
                    childHeight={'0'}
                    pinSpacerHeight={'100vh'}
                    top={0}
                >
                    <section className="section orange">
                        <div className="wrapper">
                            <h1>Layered pinning 4</h1>
                        </div>
                    </section>
                </Scrollytelling.Pin>
            </Scrollytelling.Root>
        </main>
    );
}

and style.css

:root {
    --color-black: #000;
    --color-orange: #ff4d00;
    --color-white: #fff;
}

main {
    margin-bottom: 20px;
}

h1,
p {
    font-family: Lato;
    margin: 0;
}

h1 {
    width: max-content;
}

.section {
    min-height: 100vh;
    background-color: var(--color-black);
    color: var(--color-white);
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
}

.section.orange {
    background-color: var(--color-orange);
}

.wrapper {
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
}

I also added the reset.css, which didn't work either. I also specified the childHeight with "100vh" with no effect. Do you have any idea on how to fix this? Thanks very much for this awesome project!

It didn't work when scrub is false in NextJs.

It didn't work when scrub is false in NextJs.

https://codesandbox.io/p/sandbox/frosty-lumiere-kc2vc2?file=%2Fapp%2Fpage.tsx%3A10%2C11-10%2C22

Link Readme to Docs

Breaking Change with latest GSAP versions

I installed latest gsap and scrollytelling versions, and after 2 hours trying to fix it i figured out the issue relies on scrollytelling side, as its trying to resolve frmo gsap/dist/ScrollTrigger when it should be gsap/ScrollTrigger or gsap/ScrollTrigger.js;

code:

import * as Scrollytelling from '@bsmnt/scrollytelling';
import Lenis from '@studio-freight/lenis';
import gsap from 'gsap'
import ScrollTrigger from 'gsap/ScrollTrigger'

output:

ERROR in ./node_modules/@bsmnt/scrollytelling/dist/index.mjs 56:0-52
Module not found: Error: Can't resolve 'gsap/dist/ScrollTrigger' in 'C:\Users\veil3\Desktop\Sentry\sentrysolutions.org\node_modules\@bsmnt\scrollytelling\dist'
Did you mean 'ScrollTrigger.js'?
BREAKING CHANGE: The request 'gsap/dist/ScrollTrigger' failed to resolve only because it was resolved as fully specified
(probably because the origin is strict EcmaScript Module, e. g. a module with javascript mimetype, a '*.mjs' file, or a '*.js' file where the package.json contains '"type": "module"').
The extension in the request is mandatory for it to be fully specified.
Add the extension to the request.

Types review and import conventions

Working on #30 some types came up as poorly named and some other are very similar to gsap types.

'Uncaught Error: childHeight and pinSpacerHeight are required in Pin component.' for package versions ^0.2.0 and up

Hi,

I tried updating the @bsmnt/scrollytelling dependency in your Layered pinning example (https://stackblitz.com/edit/react-ts-4dtlww?file=App.tsx). ^0.1.0 still works, everything above breaks with the error Uncaught Error: childHeight and pinSpacerHeight are required in Pin component. I don't see anything in the docs regarding this, and the error isn't super helpful either as both childHeight and pinSpacerHeight are clearly present. Do you maybe have a working example which uses the most recent package version?

onRefresh callback is not stable

 <Scrollytelling.Root
      scrub={0.75}
      callbacks={{
        onRefresh: () => {
          console.log("refresh", progress.value); // most of the time return `refresh 0` as screenshot below
          update(progress.value);
        },
      }}
    >

Expose scroller prop

Could you expose the scroller prop? https://gsap.com/docs/v3/Plugins/ScrollTrigger/scroller

Or is there another way to set the scrolling listener to another element rather than the default which is viewport?

Visualizer is blank

The visualizer is blank and not showing any information about the animations.

You can see it happening in this example from the website if you enable the visualiser on root:

https://stackblitz.com/edit/stackblitz-starters-fx6y3a

Add Animation Docs

Best place to ask questions?

Hi everyone!

I'm working on a conference talk where I'm going to build something with this library. It's going to be very silly and fun!

I was wondering, where's the best place to ask questions about the type of things I'm trying to do? Is this okay, or would you prefer a chat channel somewhere? And is this project the best place, our should I go to a bigger community like GASP?

Thanks to all of you for doing this work and sharing this library!