Viewport Helper

viewport-helper.js is a set of useful tools for interacting with the viewport.

This library includes a comprehensive set of tools for detecting if elements are in the viewport, including the ability to listen for specific elements coming in and out of the viewport.

Installation

NPM

npm install @jacobfitzp/viewport-helper

Once installed, you can require the package using:

require('@jacobfitzp/viewport-helper');

CDN

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@jacobfitzp/viewport-helper@v1.2.2/dist/viewport-helper.min.js"></script>

Usage

isElementInViewport()

Used to check if a specific element is currently in the viewport.

Parameters:

Name	Type	Required	Description
element	HTMLElement	Yes	Target element
offset	number | null	No	Viewport offset

Example Usage:

let element = document.querySelector('.some-element');

if (ViewportHelper.isElementInViewport(element)) {
    console.log('Element .some-element is currently in the viewport');
}

OnElementInViewport()

Used to keep an eye on a given element and execute a callback function once it comes into the viewport.

Parameters:

Name	Type	Required	Description
element	HTMLElement | NodeList	Yes	Target element
callback	function	Yes	Callback function
offset	number | null	No	Viewport offset
once	boolean	No	Fire event only once

Example usage:

let element = document.querySelector('.some-element'),
    elements = document.querySelector('.some-element');

ViewportHelper.onElementInViewport(element, function () {
    console.log('Element .some-name has come into the viewport');
});

/* A NodeList can also be passed */
ViewportHelper.onElementNotInViewport(elements, function (element) {
    console.log('Element in viewport:');
    console.log(element);
});

onElementNotInViewport()

Does the oposite of onElementInViewport, it executes a callback function when a given element is not in the viewport.

Parameters:

Name	Type	Required	Description
element	HTMLElement | NodeList	Yes	Target element
callback	function	Yes	Callback function
offset	number | null	No	Viewport offset
once	boolean	No	Fire event only once

Example usage:

let element = document.querySelector('.some-element'),
    elements = document.querySelector('.some-element');

ViewportHelper.onElementNotInViewport(element, function () {
    console.log('Element .some-name is no longer in the viewport');
});

/* A NodeList can also be passed */
ViewportHelper.onElementNotInViewport(elements, function (element) {
    console.log('Element not in viewport:');
    console.log(element);
});

registerListener()

Used to register custom listener functions on viewport change.

Parameters:

Name	Type	Required	Description
element	HTMLElement | NodeList	Yes	Target element
callback	function	Yes	Callback function
check	function	Yes	Check function
offset	number | null	No	Viewport offset
once	boolean	No	Fire event only once

Example usage:

let element = document.querySelector('.some-element');

ViewportHelper.registerListener(element, function () {
    console.log('Custom listener function has been triggered > .some-element has come into the viewport');
}, function () {
    return ViewportHelper.isElementInViewport(element);
});

onViewportChange()

Used to execute a callback function when the viewport changes in any way, for example if the user scrolls, resizes their screen, or rotates their device.

Parameters:

Name	Type	Required	Description
callback	function	Yes	Callback function

Example Usage:

ViewportHelper.onViewportChange(function () {
    console.log('Viewport has been changed');
});

getViewportPosition()

Used to get the top and bottom position of the viewport.

getElementPosition()

Used to get the top and bottom position of a given element.

Parameters:

Name	Type	Required	Description
element	HTMLElement	Yes	Target element

Configuration

This package can be configured by manipulating the ViewportHelper.config property, the following configuration options are available:

viewportChangeEventTriggers

An array of event types that are classed as viewport change, for example scroll, resize and orientationchange.

viewportPositionOffset

Offset the viewport position by a given amount, for example if you set the offset to 200px then elements within a 200px threshold of the viewport will be considered as being in the viewport.

This is useful if you want to do something just before elements come into the viewport, in some cases increasing this value can offer better user experience.

The offset can also be set to a nagative value which will have the oposite effect.