A tiny JavaScript library to enable CSS animations when user scrolls.

This library toggles a class to an element when it appears on viewport when user scrolls. It lets you build CSS transitions or animations launched only when user scrolls on it. Only set a few HTML attributes, and code the rest with your CSS skills.

Note that in order to not be JavaScript dependant, as default behaviour, this library add the class when the element is outside of the viewport. This way, if you have any JavaScript issue, the default state of your element will appears on scroll.
Sometimes, you may need the opposite behaviour, i.e. adding a class when the element is inside the viewport. There is an option for that.

Download – 1,85ko
Compressed, for production Download – 4,13ko
Uncompressed, for development View on GitHub

Demo

The following fake elements are generated randomly just to illustrate what you can do with this library.

The circles are set to be animated several or infinite times, the squares just once. Of course, the animations defined manually are for example. You can make whatever you want in your CSS.

Hover any of them to see their settings in the tooltip. If you want to follow one when you scroll up and down, just click on it.

How to use

Basics 

<foo data-scroll="class-name">

A CSS class name, added when this element is outside of viewport, is-outside if empty.

<foo data-scroll data-scroll-repeat=" false | true | <number> ">

optional — Specify if the class will be toggled each time the element appears in viewport or not, or a maximum number of iteration. false as default if not specified.

<foo data-scroll data-scroll-offset=" <number> ">

optional — Specify an offset in pixels to take into account from the top and bottom edges of the viewport. 0 as default if not specified.

<foo data-scroll data-scroll-reverse="true">

optional — Instead of adding the class when the element is outside of the viewport, reverse this behaviour and add the class when the element is inside the viewport, is-inside class name as default if data-scroll is empty.

In this case, you will probably need to add the class to your element as default in you code to avoid JavaScript dependency.

Examples 


<!-- Toggle '.is-outside' class when outside of viewport, just once -->
<div data-scroll> … </div>

<!-- Toggle '.mulder' class when outside of viewport, just once -->
<div data-scroll="mulder"> … </div>

<!-- Toggle '.scully' class each time when outside of viewport -->
<div data-scroll="scully" data-scroll-repeat="true"> … </div>

<!-- Toggle '.alien' class 10 times when outside of 100 pixels
     of top and bottom edges of viewport -->
<div data-scroll="alien" data-scroll-repeat="10" data-scroll-offset="100"> … </div>

Recommendation

Most of the time, when you build a transition or an animation on an element, you don’t need it to be played backward when this element goes outside of the viewport. That’s why I recommend to use these few lines of CSS:

[data-scroll].is-outside {
	transition: none;
	animation: none;
}

Advanced

Custom prefix

You can change the prefix scroll in data-scroll and every attributes to prevent conflict with another JS library. To do so, add this attribute to your <html> element with your new prefix:

<html data-onscroll-effect-custom-prefix="my-prefix">

It will so be set to all attributes like data-my-prefix.

Asynchronous needs

For asynchronous needs, you can initiate the magic with:

window.initOnScrollEffect();

Hooks

You can also add some hooks: each element with data-scroll attribute fires an insideViewport event when it appears in viewport, and an outsideViewport event when it disappears from viewport. You can add event listeners on these events, and also test the state of the element with isRepeating, repeatCount and isInViewport properties. For example:

document.querySelector("#myElement").addEventListener("insideViewport", (event) => {
	console.log(`Is still repeating: ${event.target.isRepeating}`);
}, false);

Quick start

Manually

Then, add the script into your page, and it’s done.

With npm

Install with npm:

npm install onscroll-effect

Then load onScroll Effect into your application, inside your main JS file:

import "onscroll-effect";
// or
require("onscroll-effect");

and the magic happens!

Compatibility

In addition of using ES5 version, compatibility for Internet Explorer is provided by polyfill.io which supports back to IE 7. And before you ask, yes, you can run it locally.

Contribution