A light library that does stuff when the matched elements enter or leave the viewport. Tested to work in IE9+, Edge, Gecko, Blink, and Webkit.
Hint: demos now have their own repository. Be sure to check them out.
OnScreen is available on NPM. To install it open a terminal and run…
npm install onscreen --saveNot using NPM? While I would strongly recommend you to use NPM to manage your app's dependencies, you can still download it manually.
Please note that the download link in this README file might not point to the latest version.
Once installed you can use it with your favorite module bundler.
// Using ES6 syntax (requires a transpiler)
import OnScreen from 'onscreen';
const os = new OnScreen();
// Using ES5 syntax
var OnScreen = require('onscreen');
var os = new OnScreen();Not using a module bundler? No problem! If you include OnScreen using a <script> tag it will expose a global OnScreen constructor which you can use.
<!DOCTYPE html>
<html lang="en">
<head>
<!-- Your regular head tags -->
</head>
<body>
<!-- Your regular body -->
<script type="text/javascript" src="node_modules/onscreen/dist/on-screen.umd.min.js"></script>
<script type="text/javascript">
var os = new OnScreen();
</script>
</body>
</html>The constructor accepts an options object which defaults to:
var os = new OnScreen({
tolerance: 0,
debounce: 100,
container: window
});The instance, os, has the following options:
options.tolerance is the number of pixels an element is allowed to enter its container boundaries before calling its callback. Defaults to 0.
options.debounce is the number of milliseconds to wait before calling an element's callback after the user has stopped scrolling. Defaults to 100.
options.container is the container of the elements you want to track. It accepts a string representing a CSS selector or an HTMLElement object. Defaults to window.
The instance, os, has the following methods:
Starts tracking DOM nodes that match the CSS selector and calls the supplied callback when the event occurs. Allowed events are 'enter' and 'leave'.
If no callback is given, it will re-evaluate the DOM and start tracking Nodes that were appended after the page was rendered. Is not be necessary to do this manually as OnScreen is smart enough to notice when a Node was appended to the DOM.
// Do something when an element enters the viewport
os.on('enter', '.someCSSSelector', (element) => {
// makes's the element's text red
element.style.color = 'red';
});
// Do something else when an element leaves
os.on('leave', '.someCSSSelector', (element) => {
// makes's the element's text black
element.style.color = 'black';
});Removes the event callback of a given selector.
// Stop tracking when .someCSSSelector leaves the viewport
os.off('leave', '.someCSSSelector');
// Stop tracking when .someCSSSelector enters the viewport
os.off('enter', '.someCSSSelector');Removes the scroll event listener attached to the window object.
os.destroy();Adds a scroll event listener to the window object. This method is called automatically on instantiation and should only be used if you destroyed the instance.
os.attach();This is a static method that doesn't require instantiation. The selector and container parameters can be a CSS selector string or a HTMLElement object instance. If no container is provided it will default to window. This method can be invoked with OnScreen.check('.elment', '.container').
It's pretty straight forward:
- Fork this repo
- Write a feature or fix a bug
- Update or create the tests
- Pass those tests
- Send a pull request and wait…
OnScreen (mostly) follows AirBnb's Javascript Styleguide so make sure to check it out.
There's an .editorconfig that should take care of setting up your text editor. If your editor doesn't support it, then make sure to use 4 spaces per indent, trim trailing white-space, and insert a final new line.
You'll need to run the tests through an HTTP server. I'm using http-server -s & to serve ./ on http://localhost:8080 and then run the tests with npm test.
If you're upset that I decided to ditch jQuery don't be. I plan to write a wrapper and enable OnScreen to work as a jQuery plugin, though the API will break, that's for sure. You'll need to update your code if you plan to upgrade.