https://github.com/jsonkao/react-scrollama
Simple scrollytelling with the IntersectionObserver in React.
https://github.com/jsonkao/react-scrollama
intersection-observer react scrollytelling
Last synced: 12 months ago
JSON representation
Simple scrollytelling with the IntersectionObserver in React.
- Host: GitHub
- URL: https://github.com/jsonkao/react-scrollama
- Owner: jsonkao
- License: mit
- Created: 2018-07-24T13:25:05.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2025-03-19T16:26:23.000Z (about 1 year ago)
- Last Synced: 2025-04-01T12:00:14.988Z (about 1 year ago)
- Topics: intersection-observer, react, scrollytelling
- Language: JavaScript
- Homepage: https://jsonkao.github.io/react-scrollama
- Size: 8.84 MB
- Stars: 394
- Watchers: 4
- Forks: 30
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-dataviz - React Scrollama
README
# 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](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
Sex Diversity Among Grad
Students is Stagnating
by Jason Kao
## Demo
A live demo [lives here](https://jsonkao.github.io/react-scrollama). It was debu'd at the [August 2018 ReactNYC meetup](https://www.youtube.com/watch?v=zR_LDPLMUvE).
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/jsonkao/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/jsonkao/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!
- [jsonkao](https://github.com/jsonkao)
- [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/jsonkao/react-scrollama/blob/master/src/Scrollama.js#L104) 😢. We're working on this in [#44](https://github.com/jsonkao/react-scrollama/issues/44).
- Fire previous step triggers if they were jumped
Lmk if you need these features ASAP.