Scroll Snooper

🛼 Pure JavaScript API that goes snooping around elements while scrolling

Getting started

NPM package

npm i scroll-snooper

or as a dev dependency

npm i scroll-snooper --save-dev

Import

import "scroll-snooper";

// your script

CDN

👉 CDN Hosted - jsDelivr

👉 Self hosted - Download the latest release

Quick use

Create watcher to listen to events

ScrollSnooper.create({
    trigger: document.querySelector('.block'),
    onEnter: data => {
        console.log(data);
    },
    onLeave: data => {
        console.log(data);
    },
    onScroll: data => {
        console.log(data);
    },
});

Is in viewport

console.log(ScrollSnooper.isInViewport(document.querySelector('.block')));

or only return true if at least 20% of element is appearing in viewport

console.log(ScrollSnooper.isInViewport(document.querySelector('.block'), 0.2));

Visibility

Get the number of pixels and proportion (%) of the element displaying on the viewport.

console.log(ScrollSnooper.visibility(document.querySelector('.block')));

The most visible element

Select multiple elements and pick out the most visible one based on its pixel displaying on the viewport.

console.log(ScrollSnooper.getTheMostVisible(document.querySelectorAll('.blocks')));

or use with create()

ScrollSnooper.create({
    trigger: document.querySelectorAll('.blocks'),
    isGetTheMostVisible: true,
    onChange: data => {
        console.log('onChange', data);
    },
    onFound: data => {
        console.log('onFound', data);
    },
});

Documentation

ScrollSnooper.create({}) : void

Name	Type	Default	Note
trigger	jQuery, HTMLElement	undefined	Element(s).
start	string	top bottom	Starting position, top bottom means "when the top of the trigger hits the bottom of the viewport", "center center" means "when the center of the trigger hits the center of the viewport". "top 90%" or "bottom 100px" are also accepted.
end	string	bottom top	Ending position.
onEnter	function	data => {}	A callback for when the trigger is scrolled into view.
onLeave	function	data => {}	A callback for when the trigger is scrolled out of view.
onScroll	function	data => {}	A callback that gets called everytime the scroll position changed (scrolling, resizing).

When isGetTheMostVisible is true

Name	Type	Default	Note
isGetTheMostVisible	boolean	false	Activate the watcher for multiple triggers.
onChange	function	data => {}	A callback that gets called everytime the most visible element changed (including undefined).
onFound	function	data => {}	A callback that gets called everytime one of the triggers is scrolled into view.

ScrollSnooper.isInViewport( element: jQuery | HTML element, proportion: number) : Boolean

Returns true if the element is in the viewport. You can optionally specify a minimum proportion, like ScrollSnooper.isInViewport(element, 0.2) would only return true if at least 20% of the element is in the viewport.

console.log(ScrollSnooper.isInViewport(document.querySelector('.block'), 0.2));

ScrollSnooper.visibility( element: jQuery | HTML element ) : {pixel, proportion}

Get the number of pixels and proportion (%) of the element displaying on the viewport.

console.log(ScrollSnooper.visibility(document.querySelector('.block')));

ScrollSnooper.getTheMostVisible( element: jQuery | HTML element, atLeastPixel: number ) : Object

Select multiple elements and pick out the most visible one based on its pixel displaying on the viewport.

console.log(ScrollSnooper.getTheMostVisible(document.querySelectorAll('.blocks')));

Deployment

Start dev server

npm run dev

Build production files (UMD and NPM package)

npm run prod

Build sources from ./web to ./build

npm run build

Build files from ./src to ./dist then publish to npm

npm run publish

License

MIT License

Copyright (c) 2022 Minh-Phuc Bui