BSMNT Scrollytelling Documentation

BSMNT Scrollytelling is a React library designed for creating scrollytelling animations. It is powered by GSAP ScrollTrigger but provides a component-based abstraction that simplifies the development process.

Key features include:

• Sensible Defaults: Automatically applies settings like scrub: true and ease: 'linear'.
• Lifecycle Management: Handles component mounting and unmounting (including animation cleanup) automatically.
• Position-based Animations: Allows defining animations using start and end scroll progress values instead of time-based duration.
• React Compatibility: Designed to work with React Server Components (using 'use client' internally) and supports animation composition via React Context.

In this library, a Tween is the mechanism used by the Animation component and its variants (such as Pin and Parallax) to handle property animations.

While the library follows the GSAP definition of a Tween (a high-performance property setter that calculates values based on a playhead), it implements a specific variation: instead of using a fixed duration, the library uses start and end props. These props determine the animation timing based on the scrolling progress within a <Pin /> component.

BSMNT Scrollytelling is a React-friendly abstraction over GSAP ScrollTrigger. It shifts the mental model of scroll animations from time-based durations to position-based progress defined by a start and an end point.

Key features include:

• Sensible Defaults: Automatically applies scrub: true and ease: 'linear' for smooth scroll-linked animations.
• Lifecycle Management: Handles component mounting and unmounting (cleanup) automatically to prevent memory leaks or broken animations in React.
• Component-Based Composition: Uses React Context to allow animations to be composed at any level of the component tree. While components use 'use client', their parents and children do not necessarily need to.
• Position-based Animation: Instead of defining how long an animation lasts in seconds, you define where it starts and ends relative to the scroll position.

To use BSMNT Scrollytelling, you must install the @bsmnt/scrollytelling package along with its required peer dependency, gsap.

yarn add @bsmnt/scrollytelling gsap

To run the documentation site in development mode, use the following command from the repository root:

yarn dev

The Scrollytelling Visualizer is a debugging tool used to inspect and understand created animations. It provides a visual representation of how animations are positioned within a timeline and displays their current states.

Key features include:

• Draggable Panel: The visualizer is contained within a panel that can be moved around the screen.
• Multi-timeline Support: It can handle multiple GSAP timelines, which can be toggled using a built-in dropdown menu.
• Integration: To enable the visualizer, use the debug prop on the <Root> component.

To run the main website in development mode, you must first navigate to the /website directory, configure the env URLs to match your local environment, and then run:

yarn dev

The documentation will be accessible at ${SITE_URL}/docs.

If your scrollytelling implementation requires specific GSAP plugins (such as CSSRulePlugin or TextPlugin), you must register them using the <RegisterGsapPlugins> component. This component should wrap your <Scrollytelling.Root> component to ensure the plugins are available within the scrollytelling context.

import * as Scrollytelling from "@bsmnt/scrollytelling";
import { CSSRulePlugin } from "gsap/dist/CSSRulePlugin";
import { TextPlugin } from "gsap/dist/TextPlugin";

export const BaboldComp = () => {
  return (
    <>
      <Scrollytelling.RegisterGsapPlugins plugins={[CSSRulePlugin, TextPlugin]}>
        <Scrollytelling.Root scrub={0.75}>
          <div className={s["section"]}>
            {/* ... */}
          </div>
        </Scrollytelling.Root>
      </Scrollytelling.RegisterGsapPlugins>
    </>
  );
};

The ImageSequenceCanvas component performs feature detection to determine if the browser supports modern image formats. This information is passed to your getFrameSrc function via a SupportTable object.

SupportTable Structure:

{
  supportsWebp: boolean;
  supportsAvif: boolean;
}

You should use this table to return the most optimized image format available (e.g., preferring .avif over .webp, and .webp over .jpg) to reduce bandwidth and improve performance.