BSMNT Scrollytelling: Bringing Animated Stories to Life
BSMNT Scrollytelling is an innovative library designed to create 'scrollytelling' animations—a storytelling method where animations trigger as the user scrolls through a webpage. The library is built on top of the GSAP ScrollTrigger but is adapted for seamless integration with React, a popular JavaScript library for building user interfaces.
Installation and Getting Started
To embark on using BSMNT Scrollytelling, one must install the @bsmnt/scrollytelling package, alongside its peer dependency, GSAP (GreenSock Animation Platform). You can easily add these to your project using yarn:
yarn add @bsmnt/scrollytelling gsap
Motivation and Purpose
The library was conceived at Basement Studio to address common challenges faced while building scroll animations for various websites. Over time, practitioners at Basement encountered several hurdles, such as mastering GSAP's interaction with ScrollTrigger, handling animations within React hooks like useEffect, and synchronizing animations with precise scroll progress. The need for a reusable solution led to the development of BSMNT Scrollytelling.
Key Features and Benefits
BSMNT Scrollytelling introduces a component-based method for developing scroll animations, offering key advantages:
- Sensible Defaults: Automatically applies beneficial settings for scroll animations, such as
scrub: trueandease: 'linear'. - Lifecycle Management: Efficiently handles the mounting and unmounting of React components.
- Position-based Animations: Allows defining animations using
startandendpositions rather than just time durations.
The componentized approach not only simplifies compatibility with React Server Components but also promotes the composition of animations at different tree levels through React Context.
Core Components and Usage
The library offers a range of components and utilities:
- Root: Establishes a timeline and scroll trigger, providing React Context.
- Animation: Adds animations to the timeline using the
tweenproperty to control behavior. - Waypoint: Executes callbacks or tweens at specific timeline points, optionally using
labels. - Parallax & ImageSequenceCanvas: Simplify creating parallax effects and image sequence animations.
Additionally, hooks like useScrollytelling and useScrollToLabel empower developers to enhance interactivity by consuming context or scrolling to specific labels.
Demonstration and Examples
To see the library in action, Basement Studio has crafted a demo site showcasing practical applications. Further examples explore various use cases of scrollytelling animations:
- A simple animation demo
- Integration with Lenis Smooth Scroll demo
- Layered pinning demo
- Creative Three.js Tube demo
Troubleshooting Tips
A common issue faced could be animations not triggering during scroll. The likely cause is the misalignment of the start and end values in the Root component. This might happen if the element wrapped by Root is only 100vh tall. Adjusting these values or increasing the element's height can resolve this problem.
Conclusion
BSMNT Scrollytelling embodies a cutting-edge solution for web developers, merging storytelling with interactive animations through a powerful, React-adapted interface. By simplifying the complexity of scroll animations, it enables creators to weave dynamic tales with ease and precision.