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.
- ๐ก Core Concepts
- ๐ API Reference
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. 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 anend
, 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
, andease: 'linear'
. - โ Take care of component mounting and unmounting.
- โ
Create animations with absolute positioning defined by a
start
and anend
, instead of a time-basedduration
.
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 atween
prop that will control how the animation behaves.Waypoint
: Runs a callback or tween at a specific point in the timeline. Can also receive alabel
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 thetimeline
.useScrollToLabel
: Scrolls to the label name you pass. Labels can be added with theWaypoint
component.
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
"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:
- your animation "starts when the start of the scroller hits the start of the viewport",
- your animation "ends when the bottom of the scroller hits the bottom of the viewport",
- the element your
Root
wraps around is only100vh
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/