scroll-watcher
scroll-watcher copied to clipboard
A small JavaScript library for scroll-based data-driven graphics.
scrollWatcher 📜👀
A small JavaScript library for scroll-based data-driven graphics (without any nasty scrolljacking). scrollWatcher sticks an element at a fixed position onscreen, and then provides the distance scrolled through its (much taller) parent as a percentage.
As seen on WSJ.com in How Fed Rates Move Markets and What ECB Stimulus Has Done.
Is scrollWatcher the right library for you?
- Want something to always stick on the page? Use CSS
position: fixed;
. - Want something to stick when you scroll past it? Use jQuery fixto plugin or jQuery Sticky.
- Want a sticky header that hides on scroll? Use headroom.js.
- Want to trigger events on scroll? Use Waypoints.
- If you want to use scroll as a way of interacting with a data-driven graphic without scrolljacking, use scrollWatcher.
Quickstart
-
Include jQuery and the sticky-positioning fixto plugin on the page.
-
In your HTML, you'll need a tall outer element, with one much shorter element inside of it.
<div class="outer" style="height: 2000px;"> <div class="inner"></div> </div>
-
In your JavaScript, you'll need to call
scrollWatcher
with a configuration object usingparent
andonUpdate
arguments. The function passed intoonUpdate
will run every 20 miliseconds.scrollWatcher({ parent: '.outer', onUpdate: function( scrollPercent, parentElement ){ $('.inner').text('Scrolled '+scrollPercent+'% through the parent.'); } });
Examples
Check out the source code to see how these are used.
Other features
Starting and stopping
If you create a new instance of scrollWatcher:
var myWatcher = scrollWatcher({
onUpdate: function( scrollPercent, parentElement ){
console.log('Scrolled '+scrollPercent+'% through the parent.');
},
parent: '.outer'
});
... you can then start, pause and stop at any time.
// stop checking but keep stuck
myWatcher.pause();
// stop checking and unstick
myWatcher.stop();
// start checking and restick
myWatcher.start();
Check if active
There are two read-only properties:
-
active
is true when the scrollWatcher instance is currently onscreen (and running).var isActive = myWatcher.active;
-
hasBeenActive
is true when the scrollWatcher instance has been onscreen (and run) at least once.var isOrWasActive = myWatcher.hasBeenActive;
You may want to use these to (for example) hide a "keep scrolling!" message.
Check for device support
Use scrollWatcher.supported()
to check whether or not scrollWatcher will work in the current browser.
Browser support
scrollWatcher works on all modern browsers, including IE 9 and up. However, it does not work on iOS 7 and lower due to the way Safari handles CSS position: fixed;
.
Testing
To run tests, open tests.html
in your browser and wait a couple of seconds.
Version history
v1.0.0 (April 19, 2016)
- Initial public release
License
ISC