Home

Awesome

scrollMonitor

The scroll monitor allows you to receive events when elements enter or exit a viewport. It does this using watcher objects, which watch an element and trigger events. Watcher objects also contain information about the element they watch, including the element's visibility and location relative to the viewport. If your scroll container is an element other than the body you can create a container that creates watchers.

The scroll monitor was designed to be very fast. On each scroll event the DOM is only touched twice, once to find the document height and again to find the viewport top. No variables are declared, nor are any objects, arrays, or strings created. Watchers are very cheap. Create them liberally.

The code is vanilla javascript and has no external dependencies, however the script cannot be put in the head.

Also see the React hooks, React component and the parallax library.

Basic Usage

When the body scrolls

var scrollMonitor = require("scrollmonitor"); // if you're old school you can use the scrollMonitor global.
var myElement = document.getElementById("itemToWatch");

var elementWatcher = scrollMonitor.create( myElement );

elementWatcher.enterViewport(function() {
    console.log( 'I have entered the viewport' );
});
elementWatcher.exitViewport(function() {
    console.log( 'I have left the viewport' );
});

For a scroll container

var containerElement = document.getElementById("container");

var containerMonitor = scrollMonitor.createContainer(containerElement);
// this containerMonitor is an instance of the scroll monitor
// that listens to scroll events on your container.

var childElement = document.getElementById("child-of-container");
var elementWatcher = containerMonitor.create(childElement);

elementWatcher.enterViewport(function() {
    console.log( 'I have entered the viewport' );
});
elementWatcher.exitViewport(function() {
    console.log( 'I have left the viewport' );
});

Note: an element is said to be in the viewport if it is scrolled into its parent, it does not matter if the parent is in the viewport.

Demos

Watcher Objects

Create watcher objects with scrollMonitor.create( watchItem ). An optional second argument lets you receive events before or after this element enters the viewport. See "Offsets".

watchItem can be one of the following:

Watchers are automatically recalculated on the first scroll event after the height of the document changes.

Events

Element watchers trigger six events:

  1. If the element is larger than the viewport fullyEnterViewport will be triggered when the element spans the entire viewport.
  2. If the element is larger than the viewport partiallyExitViewport will be triggered when the element no longer spans the entire viewport.

Properties

  1. If the element is larger than the viewport isFullyInViewport is true when the element spans the entire viewport.

Methods

These methods are automatically called by the scrollMonitor, you should never need them:

Locking

Sometimes you want to change the element you're watching, but want to continue watching the original area. One common use case is setting position: fixed on an element when it exits the viewport, then removing positioning when it when it reenters.

var watcher = scrollMonitor.create( $element );
watcher.lock(); // ensure that we're always watching the place the element originally was

watcher.exitViewport(function() {
    $element.addClass('fixed');
});
watcher.enterViewport(function() {
    $element.removeClass('fixed');
});

Because the watcher was locked on the second line, the scroll monitor will never recalculate its location.

Offsets

If you want to trigger an event when the edge of an element is near the edge of the viewport, you can use offsets. The offset is the second argument to scrollMonitor.create.

This will trigger events when an element gets within 200px of the viewport:

scrollMonitor.create( element, 200 )

This will trigger when the element is 200px inside the viewport:

scrollMonitor.create( element, -200 )

If you only want it to affect the top and bottom differently you can send an object in.

scrollMonitor.create( element, {top: 200, bottom: 50})

If you only want it to affect the top and not the bottom you can use only one property in.

scrollMonitor.create( element, {top: 200})

scrollMonitor Module

Methods

Properties

Contributing

There is a set of unit tests written with Mocha + Chai that run in testem. Getting them running is simple:

npm install
npm test

then open http://localhost:7357