Scroll Snooper
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
Copyright (c) 2022 Minh-Phuc Bui