Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/camwiegert/in-view
Get notified when a DOM element enters or exits the viewport. :eyes:
https://github.com/camwiegert/in-view
javascript utility viewport
Last synced: 3 months ago
JSON representation
Get notified when a DOM element enters or exits the viewport. :eyes:
- Host: GitHub
- URL: https://github.com/camwiegert/in-view
- Owner: camwiegert
- License: mit
- Archived: true
- Created: 2016-08-02T14:06:34.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2019-10-27T19:45:24.000Z (about 5 years ago)
- Last Synced: 2024-01-18T07:25:34.740Z (11 months ago)
- Topics: javascript, utility, viewport
- Language: JavaScript
- Homepage: https://camwiegert.github.io/in-view
- Size: 144 KB
- Stars: 4,663
- Watchers: 88
- Forks: 268
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# in-view.js :eyes:
Get notified when a DOM element enters or exits the viewport. A small (~1.9kb gzipped), dependency-free, javascript utility for IE9+.
[camwiegert.github.io/in-view](https://camwiegert.github.io/in-view)
[](https://travis-ci.org/camwiegert/in-view)
[](https://npmjs.com/package/in-view)
---
## Installation
Either download the [latest release](https://unpkg.com/in-view/dist/in-view.min.js) and include it in your markup or install with [npm](http://npmjs.com/package/in-view):
```sh
npm install --save in-view
```
---
## Basic Usage
With in-view, you can register handlers that are called when an element **enters** or **exits** the viewport. Each handler receives one element, the one entering or exiting the viewport, as its only argument.
```js
inView('.someSelector')
.on('enter', doSomething)
.on('exit', el => {
el.style.opacity = 0.5;
});
```
---
## API
in-view maintains a separate handler registry for each set of elements captured with `inView()`. Each registry exposes the same four methods. in-view also exposes four top-level methods. (`is`, `offset`, `threshold`, `test`).
### inView(\).on(\, \)
> Register a handler to the elements selected by `selector` for `event`. The only events in-view emits are `'enter'` and `'exit'`.
> ```js
> inView('.someSelector').on('enter', doSomething);
> ```
### inView(\).once(\, \)
> Register a handler to the elements selected by `selector` for `event`. Handlers registered with `once` will only be called once.
> ```js
> inView('.someSelector').once('enter', doSomething);
> ```
### inView.is(\)
> Check if `element` is in the viewport.
> ```js
> inView.is(document.querySelector('.someSelector'));
> // => true
> ```
### inView.offset(\)
> By default, in-view considers something in viewport if it breaks any edge of the viewport. This can be used to set an offset from that edge. For example, an offset of `100` will consider elements in viewport if they break any edge of the viewport by at least `100` pixels. `offset` can be a positive or negative integer.
> ```js
> inView.offset(100);
> inView.offset(-50);
> ```
> Offset can also be set per-direction by passing an object.
> ```js
> inView.offset({
> top: 100,
> right: 75,
> bottom: 50,
> left: 25
> });
> ```
### inView.threshold(\)
> Set the ratio of an element's height **and** width that needs to be visible for it to be considered in viewport. This defaults to `0`, meaning any amount. A threshold of `0.5` or `1` will require that half or all, respectively, of an element's height and width need to be visible. `threshold` must be a number between `0` and `1`.
> ```js
> inView.threshold(0);
> inView.threshold(0.5);
> inView.threshold(1);
> ```
### inView.test(\)
> Override in-view's default visibility criteria with a custom function. This function will receive the element and the options object as its only two arguments. Return `true` when an element should be considered visible and `false` otherwise.
> ```js
> inView.test((el, options) => {
> // ...
> });
> ```
### inView(\).check()
> Manually check the status of the elements selected by `selector`. By default, all registries are checked on `window`'s `scroll`, `resize`, and `load` events.
> ```js
> inView('.someSelector').check();
> ```
### inView(\).emit(\, \)
> Manually emit `event` for any single element.
> ```js
> inView('.someSelector').emit('exit', document.querySelectorAll('.someSelector')[0]);
> ```
---
## Browser Support
**in-view supports all modern browsers and IE9+.**
As a small caveat, in-view utilizes [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) to check the visibility of registered elements after a DOM mutation. If that's functionality you need in IE9-10, consider using a [polyfill](https://github.com/webcomponents/webcomponentsjs/blob/master/src/MutationObserver/MutationObserver.js).
---
## Performance
Any library that watches scroll events runs the risk of degrading page performance. To mitigate this, currently, in-view only registers a single, throttled (maximum once every 100ms) event listener on each of `window`'s `load`, `resize`, and `scroll` events and uses those to run a check on each registry.
### Utilizing IntersectionObserver
There's an emerging browser API, [`IntersectionObserver`](https://wicg.github.io/IntersectionObserver/), that aims to provide developers with a performant way to check the visibility of DOM elements. Going forward, in-view will aim to delegate to `IntersectionObserver` when it's supported, falling back to polling only when necessary.
---
**License** [MIT](https://opensource.org/licenses/MIT)