onscreen
Version:
A light library that does stuff when the matched elements enter or leave the viewport
195 lines (133 loc) • 7.43 kB
Markdown
[](https://travis-ci.org/silvestreh/onScreen)
[](https://codecov.io/gh/silvestreh/onScreen)
[](https://www.codacy.com/app/silvestre-herrera/onScreen?utm_source=github.com&utm_medium=referral&utm_content=silvestreh/onScreen&utm_campaign=Badge_Grade)
[](https://david-dm.org/silvestreh/onScreen#info=devDependencies&view=table)
[](https://david-dm.org/silvestreh/onScreen#info=dependencies&view=table)
[](https://www.npmjs.com/package/onscreen)
[](https://www.npmjs.com/package/onscreen)
[](https://www.npmjs.com/package/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](https://github.com/silvestreh/onScreen-demo).
### Installation
OnScreen is available on NPM. To install it open a terminal and run…
```shell
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](https://unpkg.com/onscreen/dist/on-screen.umd.min.js).
#### 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:
```json
dependencies: {
"onscreen": "https://unpkg.com/onscreen/dist/on-screen.umd.min.js"
}
```
Or, from your command line, run the following:
```shell
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.
```javascript
// 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.
```html
<!DOCTYPE html>
<html lang="en">
<head>
<!-- Your regular head tags -->
</head>
<body>
<!-- Your regular body -->
<script type="text/javascript" src="https://unpkg.com/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:
```javascript
var os = new OnScreen({
tolerance: 0,
debounce: 100,
container: window
});
```
#### Options
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`.
#### Methods
The instance, `os`, has the following methods:
##### `on(event, selector, [callback])`
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. It's not necessary to do this manually as OnScreen is smart enough to notice when a Node was appended to the DOM.
```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`.
```javascript
// 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.
```javascript
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.
```javascript
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](https://github.com/airbnb/javascript) 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.