# React Scrollama 🦙🦙

npm version

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](https://russellsamora.github.io/) [Scrollama](https://github.com/russellgoldenberg/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](https://squirrelsquirrel78.github.io/react-scrollama).
Basic step triggers Sticky graphic on the side
## Install React Scrollama can be installed as an [npm package](https://www.npmjs.com/package/react-scrollama): ``` $ npm install react-scrollama ``` ## Usage A `Scrollama` component wraps a set of steps. Each `Step` component [must](https://github.com/squirrelsquirrel78/react-scrollama/issues/19#issuecomment-624861326) 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](#scrollama) 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) => (
I'm a Scrollama Step of index {stepIndex}
))}
); }; export default ScrollamaDemo; ``` ## 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. ### `Scrollama` 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 original `IntersectionObserver` entry } ``` 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 original `IntersectionObserver` entry } ``` To create a fixed graphic with text scrolling beside/over it, use `position: sticky;`. [How to use position sticky.](https://pudding.cool/process/scrollytelling-sticky/) ### `Step` 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](https://github.com/squirrelsquirrel78/react-scrollama/issues/19#issuecomment-624861326) 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](https://reactjs.org/docs/lists-and-keys.html)). ## Thank you to everyone who made this possible! - [maerzhase](https://github.com/maerzhase) - [NicholasLYang](https://github.com/NicholasLYang) - [jonesbp](https://github.com/jonesbp) - [kennethormandy](https://github.com/kennethormandy) - [cedricdelpoux](https://github.com/cedricdelpoux) - [davidnmora](https://github.com/davidnmora) - [jefffriesen](https://github.com/jefffriesen) - [paolocorti](https://github.com/paolocorti) - [elbertwang3](https://github.com/elbertwang3) - [michaelgrotton](https://github.com/michaelgrotton) - [jjrchrds](https://github.com/jjrchrds) - [goleary](https://github.com/goleary) - [danieleguido](https://github.com/danieleguido) - [Lane](https://github.com/Lane) - [jkjustjoshing](https://github.com/jkjustjoshing) - [tuckergordon](https://github.com/tuckergordon) - [fschwander](https://github.com/fschwander) - [thisispaul](https://github.com/thisispaul) ## Features roadmap - Currently, there is no way to throttle/customize React Scrollama's [resize listener](https://github.com/squirrelsquirrel78/react-scrollama/blob/master/src/Scrollama.js#L104) 😢. We're working on this in [#44](https://github.com/squirrelsquirrel78/react-scrollama/issues/44). - Fire previous step triggers if they were jumped Lmk if you need these features ASAP.