npm.io
2.1.0 • Published 1 month ago

scroll-snooper

Licence
MIT
Version
2.1.0
Deps
0
Size
18 kB
Vulns
0
Weekly
0
Stars
12

Scroll Snooper

CodePen npm version npm downloads jsdelivr hits GitHub stars GitHub release license Made in Vietnam

Pure JavaScript API that goes snooping around elements while scrolling

Demo https://phucbm.github.io/scroll-snooper/

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({}) : {destroy}
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).

create() returns an object with a destroy() method to stop watching and remove the markers.

const snooper = ScrollSnooper.create({trigger: document.querySelector('.block')});

// later
snooper.destroy();

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

# Install dependencies
pnpm install

# Start dev server
pnpm dev

# Build production files (UMD and NPM package) from ./src to ./dist
pnpm prod

# Build demo site from ./web to ./build
pnpm build

The demo site is deployed to GitHub Pages on every push to main.

Publish

Publishing to NPM is automated by publish-npm-action via OIDC trusted publishing. Create a GitHub release with a tag like v2.1.0: the workflow sets package.json to that version, builds dist/, commits both back to main and publishes the package.

License

MIT License

Copyright (c) 2022 Minh-Phuc Bui

Keywords