Skip to content

martinlaxenaire/scroll-observer

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

7 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Lightweight vanilla javascript library to handle intersection observers

Initializing

import {ScrollObserver} from './src/scroll.observer.js';

const scrollObserver = new ScrollObserver();

In a browser, you can use the UMD files located in the dist directory:

<script src="dist/scroll.observer.umd.js"></script>
const scrollObserver = new ScrollObserver();

Parameters

Basic params

The basic parameters you can specify are the same you'd use with an intersection observer (see https://developer.mozilla.org/fr/docs/Web/API/Intersection_Observer_API):

Parameter Type Default Description
root CSS selector "viewport" Root intersection observer parameter
rootMargin String "0px" Root margins to use
threshold array 0 Array of thresholds that will trigger the callback function
const scrollObserver = new ScrollObserver({
    // root
    root: document.getElementById("content"),
    // rootMargins
    rootMargin: "20px 0",
    // threshold array
    threshold: [0, 0.25, 0.5, 0.75, 1]
});

Observe elements

Once you've created an observer, you need to observe elements.

You can add one or multiple elements to observe thanks to the observe() method:

scrollObserver.observe({
    // elements to observe
    elements: document.querySelectorAll(".scroll-observed-el")
});

You can use a CSS selector instead of a list of elements:

// exactly the same as above
scrollObserver.observe({
    // elements to observe specified with a selector
    selector: ".scroll-observed-el"
});

There are 3 callbacks that you can use when observing an element, onBeforeElVisible(), onElVisible() and onElHidden, trigger by the intersection observer based on the root, rootMargin and threshold parameters:

scrollObserver.observe({
    // elements to observe
    elements: document.querySelectorAll(".scroll-observed-el"),
    // wait for 200ms (cumulative) each time one of this element is visible
    stagger: 200,
    // an ".scroll-observed-el" element became visible
    onBeforeElVisible: (observedEl) => {
        // observedEl is an object containing the original HTML element, its bounding rectangle and other properties
        console.log(observedEl);
    },
    // an ".scroll-observed-el" element became visible and its staggering timeout has run
    onElVisible: (observedEl) => {
        // observedEl is an object containing the original HTML element, its bounding rectangle and other properties
        console.log(observedEl);
    },
    // an ".scroll-observed-el" element became hidden
    onElHidden: (observedEl) => {
        // observedEl is an object containing the original HTML element, its bounding rectangle and other properties
        console.log(observedEl);
    },
});

Complete parameter list

Here is a complete list of all observe() method parameters:

Parameter Type Default Description
elements array of HTML elements [] elements to observe
selector string null elements to observe based on a CSS selector
keepObserving bool false Whether we should keep observing the element after it has been in and out of view
triggerRatio float between 0 and 1 0 The ratio at which the visible/hidden callback should be called
alwaysTrigger bool true Whether it should trigger the visible callback multiple times or just once
stagger float 0 Number of milliseconds to wait before calling the visible callback (used for staggering animations)
onBeforeElVisible function(observedEl) void Function to execute right when this element become visible. Use it to change this element staggering property for example
onElVisible function(observedEl) void Function to execute when this element become visible, after the staggering timeout
onElHidden function(observedEl) void Function to execute when this element become hidden

Unobserve elements

You can decide to stop observing elements whenever you want.

Unobserving one element

You can pass a HTML element to the unobserveEl() method:

scrollObserver.unobserveEl(document.getElementById("observed-el"));

Unobserving multiple elements

You can pass an array of elements to the unobserveEls() method:

scrollObserver.unobserveEls(document.querySelectorAll(".scroll-observed-el"));

Unobserving all elements and disconnect observer

You can also decide to unobserve all elements and disconnect your observer:

scrollObserver.unobserveAll();

Events

There are 4 events you can use, onError(), onBeforeElVisible(), onElVisible() and onElHidden():

scrollObserver.onError(() => {
    // intersection observer API is not supported, do something
}).onBeforeElVisible((observedEl) => {
    // called each time an observed element become visible
    console.log(observedEl);
}).onElVisible((observedEl) => {
    // called each time an observed element become visible but after its staggering timeout
    console.log(observedEl);
}).onElHidden((observedEl) => {
    // called each time an observed element become hidden
    console.log(observedEl);
});

Releases

No releases published

Packages

No packages published