BSMNT Scrollytelling

https://scrollytelling.basement.studio/docs
Admin
BSMNT Scrollytelling is a component-based library designed to simplify the creation of scroll...
Tokens:4,661
Snippets:15
Trust Score:8.6
Update:1 year ago
Show doc for...
Tokens:
Raw
### BSMNT Scrollytelling Animation Implementation

Source: https://scrollytelling.basement.studio/docs/index

This example shows how to implement scroll animations using the BSMNT Scrollytelling library. It utilizes components like `Root` and `Animation` for a declarative approach, simplifying animation definitions and lifecycle management.

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

const Component = () => {
  return (
    <Scrollytelling.Root>
      <div className="container">
        <Scrollytelling.Animation
          tween={{ start: 0, end: 30, from: { opacity: 0, scale: 0.9 } }}
        >
          <h1 className="title">Hello World</h1>
        </Scrollytelling.Animation>
        <Scrollytelling.Animation
          tween={[
            { start: 30, end: 80, to: { rotate: 360 } },
            { start: 80, end: 100, to: { y: 100 } },
          ]}
        >
          <div className="box" />
        </Scrollytelling.Animation>
      </div>
    </Scrollytelling.Root>
  );
};

```

--------------------------------

### GSAP ScrollTrigger Animation Example

Source: https://scrollytelling.basement.studio/docs/index

This code snippet demonstrates a typical scroll-based animation using GSAP and ScrollTrigger directly. It requires manual setup of the timeline, ScrollTrigger, and cleanup within useEffect.

```jsx
'use client' ;

import { gsap } from 'gsap' ;
import Scr011Trigger from 'gsap/dist /Scr011Trigger ' ;
import { useEffect } from 'react' ;

const Component = () => {
  useEffect(() => {
    gsap.registerPlugin(ScrollTrigger);

    const timeline = gsap.timeline({
      scr011Trigger: {
        scrub: true,
        trigger: ".container",
      },
    });

    timeline.from(".title"), {opacity: 0, scale: 0.9, duration: 0.5});
    timeline.to(".box", {rotate: 360, duration: 2});
    timeline.to(".box", {y: 100, duration: 0.3});

    return () => {
      timeline.revert();
    };
  }, []);

  return (
    <div className="container">
      <h1 className="title">Hello World</h1>
      <div className="box" />
    </div>
  );
};

```

--------------------------------

### Root Component Usage with Animation in React

Source: https://scrollytelling.basement.studio/docs/api-reference/root

Demonstrates how to use the Scrollytelling Root component to set up a scroll-triggered timeline and an Animation component for animating a child element. It highlights common props like 'start', 'debug', and 'tween' for configuration.

```javascript
import * as Scrollytelling from "@bsmnt/scrollytelling";
 
export const Footer = () => (
  <Scrollytelling.Root start="top 80%" debug={{ label: "Footer" }}>
    <footer className={s.footer}>
      <div className={s["container"]}>
        <Scrollytelling.Animation
          tween={{
            start: 60,
            end: 100,
            from: {
              y: "-120%",
              position: "absolute",
              x: isDesktopSm ? "-8vw" : toVw(-20),
              scale: 0.6,
            },
          }}>
          <a href={ghHref} target="_blank" rel="noreferrer">
            <Image className={s.QR} src={QRImg} alt="QR" />
          </a>
        </Scrollytelling.Animation>
      </div>
    </footer>
  </Scrollytelling.Root>
);
```

--------------------------------

### Using Animation Component in React

Source: https://scrollytelling.basement.studio/docs/api-reference/animation

Demonstrates how to use the `<Animation>` component to animate a child `<h1>` element as the user scrolls. It utilizes the `tween` prop to define the animation's start, end, and target transformations. The component is nested within a `<Scrollytelling.Root>` for scroll-based context.

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

export const HomePage = () => (
  <Scrollytelling.Root disabled={isDisabled} key={i} debug={{ label: "texts" }}>
    <div style={{ height: "200vh", background: "black" }}>
      <div style={{ position: "sticky", top: 0 }}>
        <Scrollytelling.Animation
          tween={{
            start: 0,
            end: 100,
            to: { scale: 1.5 },
          }}
        >
          <h1
            style={{
              fontSize: "5rem",
              transformOrigin: "top left",
            }}
          >
            This is a text
          </h1>
        </Scrollytelling.Animation>
      </div>
    </div>
  </Scrollytelling.Root>
);
```

--------------------------------

### React Stagger Component for Staggered Animations

Source: https://scrollytelling.basement.studio/docs/api-reference/stagger

Demonstrates how to use the `<Stagger>` component from '@bsmnt/scrollytelling' to animate multiple child elements with staggered start times. It takes an `overlap` factor and a `tween` configuration for animation, and accepts children to be animated. The `disabled` prop can be used to turn off animations.

```javascript
import * as Scrollytelling from "@bsmnt/scrollytelling";
 
export const HomePage = () => (
  <Scrollytelling.Root>
    <Scrollytelling.Stagger
      overlap={0.2}
      tween={{
        start: 0,
        end: 100,
        // Animation configuration here
      }}
    >
      <div className="animated-element">Element 1</div>
      <div className="animated-element">Element 2</div>
      <div className="animated-element">Element 3</div>
    </Scrollytelling.Stagger>
  </Scrollytelling.Root>
);
```

--------------------------------

### Pin Component Usage with Scrollytelling Root

Source: https://scrollytelling.basement.studio/docs/api-reference/pin

This code snippet demonstrates how to use the `<Pin>` component from the `@bsmnt/scrollytelling` library within a `<Scrollytelling.Root>`. It shows how to configure the `childHeight`, `pinSpacerHeight`, and `top` props for basic pinning functionality. The `Pin` component itself wraps content that will be pinned.

```javascript
import * as Scrollytelling from "@bsmnt/scrollytelling";
 
export const HomePage = () => (
  <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>
);
```

--------------------------------

### Root Component Props

Source: https://scrollytelling.basement.studio/docs/api-reference/root

Configuration options for the Root component, including animation start/end points, debugging features, and callbacks.

```APIDOC
## Root Component Props

### Description
Props available for the Scrollytelling Root component to configure scroll-triggered animations.

### Method
N/A (Component Props)

### Endpoint
N/A (Component Props)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A

### Props Table

#### Render Props

| Prop         | Type              | Details                                                                    |
|--------------|-------------------|----------------------------------------------------------------------------|
| `children`   | `React.ReactNode` | Optional: Children to animate, provide context to                          |
| `debug`      | `object`          | Optional: Enables debugging features. See `debug` Props for details.       |
| `start`      | `enum`            | Optional: Start position of the scroll-triggered animation timeline.       |
| `end`        | `enum`            | Optional: End position of the scroll-triggered animation timeline.         |
| `callbacks`  | `enum`            | Optional: Includes callbacks for various ScrollTrigger events.             |
| `scrub`      | `boolean | number`| Optional: Whether the animation should scrub (move proportionally with scroll).|
| `defaults`   | `object`          | Optional: An object of default values for the GSAP tween.                  |
| `toggleActions`| `enum`            | Optional: Sets how the anim is handled at toggle points.                   |
| `trigger`    | `string | HTMLElement` | Optional: Triggers the scroll animation. Can be a DOM element or selector.   |
| `disabled`   | `boolean`         | Optional: To disable the Scrollytelling component.                         |

#### `debug` Props

| Prop       | Type                       | Details                                   |
|------------|----------------------------|-------------------------------------------|
| `label`    | `string`                   | Optional: Label for the debug overlay.    |
| `visualizer`| `boolean | undefined`      | Optional: Enable/disable visualizer.      |
| `markers`  | `boolean | undefined`      | Optional: Enable/disable timeline markers.|

```

--------------------------------

### Root Component

Source: https://scrollytelling.basement.studio/docs/api-reference/root

The Root component allows for the creation of timelines, scrollTriggers, and their configuration. It also provides React Context for managing animation states.

```APIDOC
## Root Component

### Description
Allows the creation of timelines, scrollTrigger and their configuration; provides React Context.

### Method
N/A (Component)

### Endpoint
N/A (Component)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```javascript
import * as Scrollytelling from "@bsmnt/scrollytelling";

export const Footer = () => (
  <Scrollytelling.Root start="top 80%" debug={{ label: "Footer" }}>
    <footer className={s.footer}>
      <div className={s["container"]}>
        <Scrollytelling.Animation
          tween={{
            start: 60,
            end: 100,
            from: {
              y: "-120%",
              position: "absolute",
              x: isDesktopSm ? "-8vw" : toVw(-20),
              scale: 0.6,
            },
          }}
        >
          <a href={ghHref} target="_blank" rel="noreferrer">
            <Image className={s.QR} src={QRImg} alt="QR" />
          </a>
        </Scrollytelling.Animation>
      </div>
    </footer>
  </Scrollytelling.Root>
);
```

### Response
#### Success Response (200)
N/A (Component renders UI)

#### Response Example
N/A
```

--------------------------------

### Waypoint Component API

Source: https://scrollytelling.basement.studio/docs/api-reference/waypoint

Details on the Waypoint component's props and usage for triggering tweens or functions based on scroll position.

```APIDOC
## Waypoint Component

### Description

The `Waypoint` component allows you to determine a point in a timeline to trigger a tween or function based on the user's scroll progress.

### Props

#### Render Props

- **at** (number) - Required - Scrolled percentage of timeline at which the waypoint is triggered.
- **children** (React.ReactNode) - Optional - Children to animate.
- **tween** (SimpleTween & { target?: TweenTarget }) - Optional - Tween configuration and target, applied when the waypoint is triggered.
- **onCall** (() => void) | undefined - Optional - Callback function executed when the waypoint is triggered.
- **onReverseCall** (() => void) | undefined - Optional - Callback function executed when the waypoint is triggered in reverse.
- **label** (string | undefined) - Optional - A label for the waypoint.
- **disabled** (boolean | undefined) - Optional - Determines if the waypoint is disabled. Defaults to `false`.

### Usage Example

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

export const HomePage = () => (
  <Scrollytelling.Root>
    <div id="fun-div">
      <Scrollytelling.Waypoint at={50} onCall={triggerConfetti} />
      <Scrollytelling.Waypoint
        at={75}
        tween={{
          target: ["#fun-div"],
          to: { background: "black", color: "white" },
          duration: 0.35,
        }}
      />
    </div>
  </Scrollytelling.Root>
);
```
```

--------------------------------

### Pin Component API

Source: https://scrollytelling.basement.studio/docs/api-reference/pin

The Pin component allows you to fix an element in place while the rest of the content scrolls. It ensures the pinned element remains stationary at its initial position during the Scrollytelling active period.

```APIDOC
## Pin Component API

### Description
The `Pin` component enables pinning an element in its initial position while the remaining content scrolls. It ensures that the pinned element stays fixed at its starting position within the active duration of Scrollytelling.

### Method
This is a React component, not an HTTP method.

### Endpoint
This is a React component, not an HTTP endpoint.

### Props
#### Props
- **tween** (string | number) - Height of the pinned element in the pin
- **pinSpacerHeight** (string | number) - Height of the spacer reserved for the pinned element in the pin
- **childClassName** (string) - Optional: Custom CSS class name for the child element
- **children** (React.ReactNode) - Optional: Content to be rendered inside the pinned element
- **pinSpacerClassName** (string) - Optional: Custom CSS class name for the pin spacer element
- **top** (string | number) - Optional: Custom top position for the pinned element (Default: `0`)

### Usage Example
```jsx
import * as Scrollytelling from "@bsmnt/scrollytelling";
 
export const HomePage = () => (
  <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>
);
```

### Further Examples
- Basic Usage: https://stackblitz.com/edit/react-ts-kittrj
- With Horizontal Scrolling: https://stackblitz.com/edit/stackblitz-starters-fx6y3a
```

--------------------------------

### Scrollytelling Waypoint Component Usage

Source: https://scrollytelling.basement.studio/docs/api-reference/waypoint

Demonstrates how to import and use the Waypoint component within a React application using Scrollytelling. It shows triggering a function and applying a GSAP tween based on scroll position.

```javascript
import * as Scrollytelling from "@bsmnt/scrollytelling";
 
export const HomePage = () => (
  <Scrollytelling.Root>
    <div id="fun-div">
      <Scrollytelling.Waypoint at={50} onCall={triggerConfetti} />
      <Scrollytelling.Waypoint
        at={75}
        tween={{
          target: ["#fun-div"],
          to: { background: "black", color: "white" },
          duration: 0.35,
        }}
      />
    </div>
  </Scrollytelling.Root>
);
```

--------------------------------

### Register GSAP Plugins with Scrollytelling

Source: https://scrollytelling.basement.studio/docs/utils/register-gsap-plugins

Registers custom GSAP plugins for specific use cases within the Scrollytelling framework. This component takes an array of GSAP plugins as a prop, making them available for use in animations. It is typically used to enable advanced GSAP features like CSSRulePlugin and TextPlugin.

```javascript
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"]}>
//...
      </Scrollytelling.Root>
      </Scrollytelling.RegisterGsapPlugins>
    </>
  );
};
```

--------------------------------

### React Parallax Component Usage with GSAP

Source: https://scrollytelling.basement.studio/docs/api-reference/parallax

Demonstrates how to import and use the Parallax component from the @bsmnt/scrollytelling library in a React application. It shows the basic structure for applying a vertical parallax movement to a paragraph element based on scroll progress.

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

export const HomePage = () => (
  <Scrollytelling.Root>
    <Scrollytelling.Parallax
      tween={{
        start: 0,
        end: 100,
        movementY: { value: 40, unit: "px" },
      }}
    >
      <p>This text will move on scroll</p>
    </Scrollytelling.Parallax>
  </Scrollytelling.Root>
);
```

--------------------------------

### Stagger Component API

Source: https://scrollytelling.basement.studio/docs/api-reference/stagger

The Stagger component allows you to create staggered animations for a group of elements, with options for controlling overlap and animation properties.

```APIDOC
## Stagger Component

### Description
The `Stagger` component enables staggered animations that start at different times (with optional overlaps) for a group of elements.

### Method
This is a React component, not an HTTP endpoint.

### Endpoint
N/A (Component Usage)

### Parameters
#### Props
- **children** (React.ReactNode) - Optional - Children to animate
- **overlap** (number) - Optional - Overlap factor for animations (0 to 1)
- **tween** (TweenWithChildrenDef | TweenWithTargetDef) - Required - Animation config and target
- **disabled** (boolean) - Optional - Disable animations, Default: `false`

### Request Example
```jsx
import * as Scrollytelling from "@bsmnt/scrollytelling";
 
export const HomePage = () => (
  <Scrollytelling.Root>
    <Scrollytelling.Stagger
      overlap={0.2}
      tween={{
        start: 0,
        end: 100
      }}
    >
      <div className="animated-element">Element 1</div>
      <div className="animated-element">Element 2</div>
      <div className="animated-element">Element 3</div>
    </Scrollytelling.Stagger>
  </Scrollytelling.Root>
);
```

### Response
This component renders animated elements. There is no direct HTTP response.

#### Success Response (Component Render)
- Elements are rendered with staggered animations applied.

#### Response Example
(Visual output of animated elements)
```

--------------------------------

### Parallax Component API

Source: https://scrollytelling.basement.studio/docs/api-reference/parallax

The Parallax component applies a parallax effect to its children using GSAP animations. It accepts tween configuration and children elements to animate.

```APIDOC
## Parallax Component

### Description
Applies a parallax effect to its children using GSAP animations.

### Component Signature
`<Parallax tween? tweenConfig children? React.ReactNode disabled? boolean />`

### Props

#### Render Props
- **tween** (object) - Optional - Configuration for the GSAP tween. See `Parallax Tween Props` below.
- **children** (React.ReactNode) - Optional - The child element(s) to apply the parallax effect to.
- **disabled** (boolean) - Optional - Disables the parallax animation. Defaults to `false`.

#### Parallax Tween Props
- **start** (number) - Required - The scroll progress value (0-100) where the movement starts.
- **end** (number) - Required - The scroll progress value (0-100) where the movement ends.
- **target** (TweenTarget) - Optional - The target element or elements to apply the animation to.
- **movementX** (UnitValue) - Optional - The amount of movement on the X-axis. Requires `movementY` to be unset.
- **movementY** (UnitValue) - Optional - The amount of movement on the Y-axis. Requires `movementX` to be unset.

**Note:** Either `movementX` or `movementY` is required for the Parallax to work.

### Usage Example
```javascript
import * as Scrollytelling from "@bsmnt/scrollytelling";
 
export const HomePage = () => (
  <Scrollytelling.Root>
    <Scrollytelling.Parallax
      tween={{
        start: 0,
        end: 100,
        movementY: { value: 40, unit: "px" },
      }}
    >
      <p>This text will move on scroll</p>
    </Scrollytelling.Parallax>
  </Scrollytelling.Root>
);
```

### External Resources
- [GSAP Animations](https://greensock.com/gsap/) (opens in a new tab)
- [Parallax StackBlitz Example](https://stackblitz.com/edit/react-ts-wkxnja) (opens in a new tab)
```
Tokens:
Raw