onScreen

OnScreen

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.

Documentation

Hint: demos now have their own repository. Be sure to check them out.

Installation

OnScreen is available on NPM. To install it open a terminal and run…

npm install onscreen --save

Not using NPM? While I would strongly recommend you to use NPM to manage your app's dependencies, you can still download it manually.

Using bower?

While OnScreen is no longer published as a bower package you can still pull it from UnPKG by adding this to your bower.json file:

dependencies: {
    "onscreen": "https://unpkg.com/onscreen/dist/on-screen.umd.min.js"
}

Or, from your command line, run the following:

bower install --save onscreen=https://unpkg.com/onscreen/dist/on-screen.umd.min.js

Usage

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 `

The constructor accepts an `options` object which defaults to:

```javascript
var os = new OnScreen({
    tolerance: 0,
    debounce: 100,
    container: window
});

…

javascript
// Do something when an element enters the viewport
os.on('enter', '.someCSSSelector', (element, event) => {
    // makes's the element's text red
    element.style.color = 'red';

    // `event` is a string that tells you what type of event it is.
    // in this case it would be 'enter'
});

// Do something else when an element leaves
os.on('leave', '.someCSSSelector', (element, event) => {
    // makes's the element's text black
    element.style.color = 'black';

    // `event` is a string that tells you what type of event it is.
    // in this case it would be 'leave'
});

// Do another thing when the element enters the viewport
os.on('enter', '.someCSSSelector', function myCallback(element, event) {
    // This callback won't override the previous one. Both will run.

    // makes the element's font size 32px
    element.style.fontSize = '32px';

    // `event` is a string that tells you what type of event it is.
    // in this case it would be 'enter'
});

As you can see in the above snippet, you can use .on() multiple times and all functions will be called.

off(event, selector, [handler])

Removes the handler (optional parameter) callback of a given selector for a given event.

// Stop tracking when .someCSSSelector leaves the viewport
os.off('leave', '.someCSSSelector', myFunction);

// Stop tracking when .someCSSSelector enters the viewport
os.off('enter', '.someCSSSelector', myOtherFunction);

If no handler is given, it'll remove all event handlers. If you want to remove an anonymous callback function you should pass the string 'anonymous' as the handler parameter.

destroy()

Removes the scroll event listener attached to the window object.

os.destroy();

attach()

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();

check(selector, container)

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').

Contributing

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…

Code style

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.

Testing

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.

jQuery

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.