React-scrolly-telling NPM

React ScrollyTelling

Create scrolly-telling animations in React with ease.

react-scrolly-telling is a helper library to track the position of an element on the screen with respect to the viewport (or other parent element). It is optimised to work well with React, SSR, and Suspense.

Docs/Demo - Storybook
GitHub / NPM / Bundlephobia

Currently this library uses modern JS API like Intersection Observer and optimised React hooks like useSyncExternalStore to keep track of element's position on the screen. In future, once ScrollTimeline API is finalised and well-supported, this library will be updated to use it.

Note: For Next 13 app router, the exports of these library can be imported by client-components only.

Installation

Install from NPM:

yarn add react-scrolly-telling
# or
npm install react-scrolly-telling
# or
pnpm add react-scrolly-telling

Note: The NPM unpacked size might show a huge number around ~200 kB. This is the install size of the package as it ships with both ESM and CJS versions, plus their respective source-maps (heavy files). The actual bundle size is quite less (few kBs). To see the effective bundle size, check Bundlephobia.

Features

Track scroll position of an element with respect to the viewport using the useScrolly hook.
element: Create ScrollyElement that are tracked automatically.
- Bonus: ScrollyElement can be used to create Horizontal Scrolling effect. See Storybook for demo.
video: Create Element with video background that plays/pauses/rewinds automatically based on scroll position.
- Place any content on top of the video element.
- Bonus: Provide a list of captions that are shown over the video based on video timestamp (in seconds). See Storybook for demo.
components: Add a RevealScrim to any ScrollyElement to reveal (fade from black) the element as the user scrolls.

`useScrolly` hook

The core hook tracks the position of an element while is scrolls with respect to the viewport (or other parent element). It returns the following values: scrollRatio, entryRatio, exitRatio and more. These values can be used to calculate styles for animations or time for video playback.

Learn more at official docs.

Usage

import { ScrollyProvider, useScrolly } from "react-scrolly-telling";

function MyComponent () {
  const ref = useRef<HTMLDivElement>(null);
  const { scrollRatio, entryRatio, exitRatio } = useScrolly(ref);

  return (
    <>
      <div style={{ height: "100vh" }} />
      <div ref={ref} style={{ height: "200vh" }}>
        <p>Entry: {entryRatio}</p>
        <p>Scroll: {scrollRatio}</p>
        <p>Exit: {exitRatio}</p>
      </div>
      <div style={{ height: "100vh" }} />
    </>
  );
};

function App () {
  return (
    <ScrollyProvider>
      <MyComponent>
    </ScrollyProvider>
  );
}