Scrollama

Scrollytelling with IntersectionObserver.

russellsamora/scrollama russellsamora.github.io/scrollama/basic scrollama

README

Get ready for the next release of Scrollama! 🚀

Scrollama is a modern & lightweight JavaScript library for scrollytelling

using

IntersectionObserver

in favor of scroll events.

Current version: 2.2.1

Important Changes

- Version 2.0.0+: .onContainerEnter and .onContainerExit have been deprecated in favor of CSS property position: sticky;. How to use position sticky.

- Version 1.4.0+: you must manually add the IntersectionObserver polyfill for cross-browser support. See installation for details.

Jump to examples.

Why?

Scrollytelling can be complicated to implement and difficult to make performant.

The goal of this library is to provide a simple interface for creating

scroll-driven interactives. Scrollama is focused on performance by using

IntersectionObserver

to handle element position detection.

Examples

_Note: most of these examples use D3 to keep the code concise, but this can be used

with any library, or with no library at all._

- Basic - just step

triggers

- Progress -

incremental step progress callback

- Sticky Graphic (Side by Side) -

using CSS position: sticky; to create a fixed graphic to the side of the text.

- Sticky Graphic (Overlay) -

using CSS position: sticky; to create a fixed graphic with fullscreen graphic with text overlayed.

- Mobile Pattern -

using pixels instead of percent for offset value so it doesn't jump around on scroll direction change

Installation

Note: As of version 1.4.0, the IntersectionObserver polyfill has been removed from the build. You must include it yourself for cross-browser support. Check here to see if you need to include the polyfill.

Old school (exposes the scrollama global):

``` html
<script src="https://unpkg.com/intersection-observer"></script>
<script src="https://unpkg.com/scrollama"></script>
```

New school:

```sh
npm install scrollama intersection-observer --save
```

And then import/require it:

``` js
import "intersection-observer";
import scrollama from "scrollama"; // or...
const scrollama = require("scrollama");
```

How to use

Basic

You can use this library to simply trigger steps, similar to something like

Waypoints. This is useful if you need

more control over your interactive, or you don't want to follow the sticky

scrollytelling pattern.

You can use any id/class naming conventions you want. The HTML structure should

look like:

``` html
!--you don't need the "data-step" attr, but can be useful for storing instructions for JS -->
<div class="step" data-step="a"></div>
<div class="step" data-step="b"></div>
<div class="step" data-step="c"></div>
```

``` js
// instantiate the scrollama
const scroller = scrollama();
// setup the instance, pass callback functions
scroller
.setup({
step: ".step",
})
.onStepEnter((response) => {
// { element, index, direction }
})
.onStepExit((response) => {
// { element, index, direction }
});
// setup resize event
window.addEventListener("resize", scroller.resize);
```

API

scrollama.setup([options])

_options:_

- step (string | HTMLElement[]): Selector (or array of elements) for the step elements that will trigger changes.

required

- offset (number 0 - 1, or string with "px"): How far from the top of the viewport to trigger a step. (default: 0.5) (middle of screen)

- progress (boolean): Whether to fire incremental step progress updates or

not. (default: false)

- threshold (number, 1+): The granularity of the progress interval in pixels (smaller = more granular). (default: 4)

- order (boolean): Fire previous step triggers if they were jumped. (default: true)

- once (boolean): Only trigger the step to enter once then remove listener. (default: false)

- debug (boolean): Whether to show visual debugging tools or not. (default:

false)

- parent (HTMLElement[]): Parent element for step selector (use if you steps are in shadow DOM) (default: undefined)

scrollama.onStepEnter(callback)

Callback that fires when the top or bottom edge of a step element enters the

offset threshold.

The argument of the callback is an object: { element: DOMElement, index: number, direction: string }

element: The step element that triggered

index: The index of the step of all steps

direction: 'up' or 'down'

scrollama.onStepExit(callback)

Callback that fires when the top or bottom edge of a step element exits the

offset threshold.

The argument of the callback is an object: { element: DOMElement, index: number, direction: string }

element: The step element that triggered

index: The index of the step of all steps

direction: 'up' or 'down'

scrollama.onStepProgress(callback)

Callback that fires the progress (0 - 1) a step has made through the threshold.

The argument of the callback is an object: { element: DOMElement, index: number, progress: number }

element: The step element that triggered

index: The index of the step of all steps

progress: The percent of completion of the step (0 - 1)

scrollama.offsetTrigger([number or string])

Get or set the offset percentage. Value must be between 0-1 (where 0 = top of viewport, 1 = bottom), or a string that includes "px" (e.g., "200px"). If set, returns the scrollama instance.