Scrollama Scrollytelling — Sticky Graphic Story Steps

Scrollytelling — a graphic that stays put while text scrolls past and drives it — is the format behind most modern data journalism. The naive implementation is a scroll event listener that calls getBoundingClientRect() on every step on every scroll event, which fires hundreds of times a second and forces a layout recalculation each time. It works, and it is one of the most reliable ways to make a page feel sluggish.

Scrollama is a ~3kb wrapper around the Intersection Observer API. The browser watches the elements and tells you when a threshold is crossed, off the main thread. No scroll listener, no per-frame measurement, no throttling code to write.

The layout does most of the work

Scrollytelling is a CSS pattern before it is a JavaScript one:

.sss-scrolly { display: grid; grid-template-columns: 1fr 1fr } with .sss-sticky { position: sticky; top: 0; height: 100vh }

The graphic column sticks within the grid's bounds while the text column scrolls normally. height: 100vh is required — a sticky element with auto height sticks at whatever height its content happens to be, which is why these layouts so often drift out of vertical alignment.

Each step is min-height: 82vh, giving the reader roughly a screenful per beat. Too short and steps fire in rapid succession; too tall and the graphic sits unchanged long enough to feel broken. The padding: 30vh 0 on the step column lets the first and last steps sit centered rather than clamping to the edges.

offset is the most important setting

offset: 0.55

This is where in the viewport a step must reach before it counts as entered, as a fraction from the top. At 0 the step triggers when it touches the very top of the screen — the reader has not begun reading it and the graphic has already moved on. At 1 it triggers at the bottom, before the text is legible.

Just past halfway is the sweet spot: the reader is looking directly at the step as the graphic responds. Getting this wrong is the most common reason a scrollytelling piece feels disconnected from its own narrative.

Two callbacks, two jobs

onStepEnter fires once per step crossing and receives { element, index, direction }. Because index is supplied, the handler is a pure function of position — setActive(response.index) sets the current node, marks everything before it as done, and highlights the matching text. Discrete state, updated on discrete events.

onStepProgress fires continuously while a step is in view, giving progress from 0 to 1. That is for continuous state, here a progress bar:

((response.index * per + response.progress * per) * 100)

Each step owns 1 / steps.length of the bar, so the fill is the completed steps plus the fraction through the current one — a single continuous 0–100% across the whole story. Progress is opt-in (progress: true) because tracking it is more work than plain enter/exit events, so it stays off unless requested.

Three-state nodes

The diagram distinguishes upcoming, current, and completed rather than just on/off. Completed nodes stay at 60% opacity with a dimmed border instead of resetting to their inactive state, so scrolling back through the story shows a visible trail of where you have been. That is the small detail that makes the graphic feel like a narrative rather than a switch, and it costs one classList.toggle.

The resize call that is not optional

window.addEventListener('resize', function () { scroller.resize(); });

Scrollama measures every step's position when setup() runs and caches those offsets. A rotated phone, a resized window, or lazy-loaded content shifting the page all invalidate that cache, and without resize() every trigger point stays measured against a layout that no longer exists. Steps then fire at visibly wrong moments — a bug that never appears in desktop testing.

Reusing it

Add a .sss-step and a matching node and everything follows, since the handlers work from index and steps.length rather than hard-coded counts. The sticky graphic can be anything — a chart, a map, a canvas, a video scrubbed by progress. On narrow screens the grid collapses to one column, which is the honest mobile fallback: the graphic scrolls inline between steps rather than fighting for half a small screen. Compare with scroll pin steps for a GSAP-driven version, or scroll progress if you only need the bar.