element-inview
Get notified when a DOM element enters or exits the viewport.
Largely basd on in-view
Installation
npm install --save element-inview
Basic Usage
With element-inview
, 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.
inView('.someSelector')
.on('enter', doSomething)
.on('exit', el => {
el.style.opacity = 0.5;
});
API
element-inview
maintains a separate handler registry for each set of elements captured with inView(<selector>)
. Each registry exposes the same four methods. element-inview
also exposes four top-level methods. (is
, offset
, threshold
, test
).
inView(<selector>).on(<event>, <handler>)
Register a handler to the elements selected by
selector
forevent
. The only eventselement-inview
emits are'enter'
and'exit'
.
inView('.someSelector').on('enter', doSomething);
inView(<selector>).once(<event>, <handler>)
Register a handler to the elements selected by
selector
forevent
. Handlers registered withonce
will only be called once.
inView('.someSelector').once('enter', doSomething);
inView.is(<element>)
Check if
element
is in the viewport.
inView.is(document.querySelector('.someSelector')); // => true
inView.offset(<offset>)
By default,
element-inview
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 of100
will consider elements in viewport if they break any edge of the viewport by at least100
pixels.offset
can be a positive or negative integer.
inView.offset(100); inView.offset(-50);
Offset can also be set per-direction by passing an object.
inView.offset({ top: 100, right: 75, bottom: 50, left: 25 });
inView.threshold(<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 of0.5
or1
will require that half or all, respectively, of an element's height and width need to be visible.threshold
must be a number between0
and1
.inView.threshold(0); inView.threshold(0.5); inView.threshold(1);
inView.test(<test>)
Override
element-inview
's default visibility criteria with a custom function. This function will receive the element and the options object as its only two arguments. Returntrue
when an element should be considered visible andfalse
otherwise.inView.test((el, options) => { // ... });
inView(<selector>).check()
Manually check the status of the elements selected by
selector
. By default, all registries are checked onwindow
'sscroll
,resize
, andload
events.
inView('.someSelector').check();
inView(<selector>).emit(<event>, <element>)
Manually emit
event
for any single element.
inView('.someSelector').emit('exit', document.querySelectorAll('.someSelector')[0]);
Browser Support
element-inview
supports all modern browsers and IE9+.
As a small caveat, element-inview
utilizes 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.
Performance
Any library that watches scroll events runs the risk of degrading page performance. To mitigate this, currently, element-inview
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
, that aims to provide developers with a performant way to check the visibility of DOM elements. Going forward, element-inview
will aim to delegate to IntersectionObserver
when it's supported, falling back to polling only when necessary.
License MIT