React Scrollama 🦙🦙

React Scrollama is a simple and silky library for scrollytelling. It relies on IntersectionObserver and sticky positioning over scroll listeners. It is originally adapted from Russel Samora's Scrollama.

A few examples of ambitious interactive stories that were built with React Scrollama…

17 interactive visualization stories using React Scrollama for scrollytelling
Comment Tati a imprimé sa marque à Barbès by Fabien Casaleggio
The scramble to secure America’s voting machines by Beatrice Jin

Demo

A live demo lives here.

Basic step triggers	Sticky graphic on the side

Install

React Scrollama can be installed as an npm package:

``$ npm install react-scrollama`

`Usage`

A Scrollama component wraps a set of steps. Each Step component must wrap a DOM element (i.e. not just text).

`jsx

...

...

provides an interface for listening in on scroll triggers like entering or exiting a step. (Here's a full list of available props.)

A basic example:

`jsx import React, { useState } from 'react'; import { Scrollama, Step } from 'react-scrollama';

const ScrollamaDemo = () => { const [currentStepIndex, setCurrentStepIndex] = useState(null);

// This callback fires when a Step hits the offset threshold. It receives the // data prop of the step, which in this demo stores the index of the step. const onStepEnter = ({ data }) => { setCurrentStepIndex(data); };

return (


      
        I'm sticky. The current triggered step index is: {currentStepIndex}
      

      
        {[1, 2, 3, 4].map((_, stepIndex) => (
          
                          style={{
                margin: '50vh 0',
                border: '1px solid gray',
                opacity: currentStepIndex === stepIndex ? 1 : 0.2,
              }}
            >
              I'm a Scrollama Step of index {stepIndex}

))}

API

React Scrollama components do not render into the DOM. They are meant to set up Intersection Observers on the elements inside the

components. In the code above, only the

 elements would show up in the DOM.
$3

These are the props you can set on the Scrollama component itself:

| Prop | Type | Default | Description | | -------------- | ---------------------------------------------------- | ------- | --------------------------------------------------------------------------------------- | | offset |number(from 0 to 1) or pixel value (e.g. "300px") | 0.3 | How far from the top of the viewport to trigger a step (as a proportion of view height) | | threshold |number(greater than 1) | 4 | Granularity of the progress interval in pixels (smaller = more granular) | | onStepEnter |function| | Callback that fires when the top or bottom edge of a step enters the offset threshold. | | onStepExit |function| | Callback that fires when the top or bottom edge of a step exits the offset threshold. | | onStepProgress |function| | Callback that fires the progress a step has made through the threshold. | | debug |boolean | false | Whether to show visual debugging tools. |

The onStepEnter and onStepExit callbacks receive one argument, an object, with the following properties:

`js { element, // The DOM node of the step that was triggered data, // The data supplied to the step direction, // 'up' or 'down' entry, // the originalIntersectionObserverentry }`

The onStepProgress callback receives one argument, an object, with the following properties:

`js { element, // The DOM node of the step that was triggered data, // The data supplied to the step progress, // The percent of completion of the step (0 to 1) direction, // 'up' or 'down' entry, // the originalIntersectionObserverentry }`

To create a fixed graphic with text scrolling beside/over it, use position: sticky;. How to use position sticky.

`$3`

A Step element can contain one child, which must be a DOM element. To use a React component as the child node, it must be wrapped with a DOM element like

.

These are the props you can set on the Step component:

| Prop | Type | Default | Description | | ---- | ---- | ------- | ---------------------------------------------------------------- | | data | any | | Data to be given to callbacks when step triggered. |

You will also probably want to set a key prop on each Step if you're transforming an array of data into a list of Step` elements (see Lists and Keys).

Thank you to everyone who made this possible!

- maerzhase
- NicholasLYang
- jonesbp
- kennethormandy
- cedricdelpoux
- davidnmora
- jefffriesen
- paolocorti
- elbertwang3
- michaelgrotton
- jjrchrds
- goleary
- danieleguido
- Lane
- jkjustjoshing
- tuckergordon
- fschwander
- thisispaul

Features roadmap

- Currently, there is no way to throttle/customize React Scrollama's resize listener 😢. We're working on this in #44.
- Fire previous step triggers if they were jumped

Lmk if you need these features ASAP.

react-scrollama