Scrolleo

A modern & lightweight Vanilla JS library for scrollytelling experiences

No dependencies, no framework, pure ESM.

Scrolleo is a modernization of scrollama with:

• Performance improvements
• Improved TypeScript definitions
• A modern ESM-only build

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. Scrolleo is focused on performance by using IntersectionObserver to handle element position detection.

View the demo gallery on GitHub Pages and checkout the source code of the examples in the demo folder:

• Basic - Basic step enter/exit functionality
• Progress - Track scroll progress through steps with visual feedback
• Sticky Side - Sticky graphic on the side with scrolling text
• Sticky Overlay - Sticky graphic overlay pattern
• Percentage Offset - Per-step offset customization using percentages
• Pixel Offset - Fixed pixel-based offsets for mobile-friendly experiences
• Multiple Instances - Multiple scrolleo instances on the same page
• Nested Scroll Container - Using a nested scroll container instead of window
• Performance Test - Performance monitoring with multiple instances

npm install @zeitonline/scrolleo

And then import it:

import scrolleo from '@zeitonline/scrolleo';

Create step elements in your HTML:

<section id="scrolly">
	<article>
		<div class="step">
			<p>Step 1</p>
		</div>
		<div class="step">
			<p>Step 2</p>
		</div>
		<div class="step">
			<p>Step 3</p>
		</div>
	</article>
</section>

Then initialize Scrolleo and set up your callbacks:

import scrolleo from '@zeitonline/scrolleo';

// Create a scrolleo instance
const scroller = scrolleo();

// Setup with options and attach callbacks
scroller
	.setup({
		step: '#scrolly article .step',
		offset: 0.5, // Trigger when step is 50% from top of viewport
		debug: false, // Set to true to see visual debugging
	})
	.onStepEnter((response) => {
		// Called when a step enters the offset threshold
		const { element, index, direction } = response;
		element.classList.add('is-active');
		console.log(`Step ${index} entered from ${direction}`);
	})
	.onStepExit((response) => {
		// Called when a step exits the offset threshold
		const { element, index, direction } = response;
		element.classList.remove('is-active');
		console.log(`Step ${index} exited to ${direction}`);
	});

The response object contains:

• element: The DOM element that triggered the callback
• index: The zero-based index of the step
• direction: Either 'up' or 'down' indicating scroll direction

options:

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'

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'

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)

direction: 'up' or 'down'

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 scrolleo instance.

This is no longer necessary with the addition of a built-in resize observer. Tell scrolleo to get latest dimensions the browser/DOM. It is best practice to throttle resize in your code, update the DOM elements, then call this function at the end.

Tell scrolleo to resume observing for trigger changes. Only necessary to call if you have previously disabled.

Tell scrolleo to stop observing for trigger changes.

Removes all observers and callback functions.

To override the offset passed in the options, set a custom offset for an individual element using data attributes. For example: <div class="step" data-offset="0.25"> or data-offset="100px".

• scrollama (the original library)
• Scroll Trigger
• Waypoints
• ScrollMagic
• graph-scroll.js
• ScrollStory
• enter-view

This project is a modernization and rebrand of scrollama by Russell Samora.

Original scrollama is licensed under the MIT License. This version maintains the same license and includes the original copyright notice. Scrolleo is maintained by DIE ZEIT / ZeitOnline.

MIT License - see LICENSE file for details.