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.
To get started, we’ll need the
@bsmnt/scrollytelling package, as well as the required peer dependency: GSAP.
yarn add @bsmnt/scrollytelling gsap
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. While preparing his talk for the React Miami Conference, JB 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
useEffectand then cleaning them up.
- Couldn’t think of scroll animations in terms of a
end, so it was hard to fire up animations at the exact scroll progress we needed to.
We aimed at componentizing a way of building scroll animations that could:
- ✅ Provide sensible defaults for scroll animations, such as
scrub: true, and
- ✅ Take care of component mounting and unmounting.
- ✅ Create animations with absolute positioning defined by a
end, instead of a time-based
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:
Root: Creates timeline and scrollTrigger, provides React Context.
Animation: Appends an animation to the timeline. Receives a
tweenprop that will control how the animation behaves.
Waypoint: Runs a callback or tween at a specific point in the timeline. Can also receive a
labelprop, 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
useScrollToLabel: Scrolls to the label name you pass. Labels can be added with the
For our talk at React Miami Conf, 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
- 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