viewability.js

Viewability.js

Viewability.js is a lightweight, dependency-free JavaScript library that tracks the visibility and viewability of a DOM element within the viewport using the IntersectionObserver and MutationObserver API. It allows developers to measure how much of an element is viewable and for how long, making it useful for ad tracking, analytics, and user engagement monitoring.

By default, the library follows the IAB Standard for viewability measurement (50% visibility for at least 1 second), but these values can be fully customized to fit specific needs.

DEMO

:star: Star me on GitHub — it motivates me a lot!

Features

• Uses IntersectionObserver for efficient viewability tracking
• Uses IAB Standard Guidelines for viewability measurement. Default to 50%, and 30% for large element sized at 242,500 pixels.
• Supports custom viewability thresholds
• Measures time in view before marking an element as fully viewed (default to 1 second)
• Uses MutationObserver for the advanced visibility detection
• Exposes a public API for manual control
• Provides an onComplete callback when the element meets the viewability criteria
• Accepts an element reference, an element ID string, or a CSS selector to specify the target element

Visibility Detection

In addition to checking if an element is within the viewport, the library includes advanced visibility checks to determine whether an element is truly visible in the viewport.

When the isVisible option is enabled (by default), the library performs additional checks to ensure an element is not just in the viewport, but actually visible:

• CSS Visibility Checks: Detects if the element is hidden using styles like display: none, visibility: hidden, opacity: 0, etc.
• Parent Visibility: Ensures that no parent element is applying styles that make the target element invisible.
• Overlapping Elements: Determines if the element is covered by another element based on the coverageThreshold (value greater than 0 and up to 1).
  • A threshold of 0.1 means that even minimal coverage will mark the element as hidden.
  • A threshold of 1 means the element must be completely covered to be considered hidden.

Installation

You can install the library via npm or simply include it in your project:

Install via npm

npm install viewability.js

Include via <script> tag

<script src="path/to/viewability.js"></script>

Usage

Selecting the Element to Monitor

The library allows you to pass:

• A direct HTMLElement reference.
• A string representing an element ID (without #).
• A CSS selector string (e.g., .class-name).

If multiple elements match a given selector, only the first one found will be tracked.

Example:

import { Viewability } from "viewability.js";

// Pass an element reference
new Viewability(document.getElementById("target"));

// Pass an ID string (equivalent to document.getElementById)
new Viewability("target");

// Pass a CSS selector (selects the first matching element)
new Viewability(".target");

Basic Example

import { Viewability } from "viewability.js";

const tracker = new Viewability("target", {
  onComplete: () => console.log("Element fully viewed!"),
  onError: (err) => console.error(err.message),
});

// or

const tracker = new Viewability("target");
tracker.onComplete = () => console.log("Element fully viewed!");
tracker.onError = (err) => console.error(err.message);

Options

Option	Type	Default	Description
autostart	Boolean	true	Automatically starts tracking on initialization.
autostop	Boolean	true	Automatically stop tracking and disconnects the observer when viewability is completed.
coverageThreshold	Number	0.1	When isVisible is true, this is the fraction of the element's area that must be covered in order to consider the element as covered (greater than 0 and up to 1).
inViewThreshold	Number	0.5	Percentage of the element that must be visible (0 to 1).
isVisible	Boolean	true	Whether to check if the element is truly visible in the viewport.
timeInView	Number	1000	Time (in milliseconds) the element must remain in view to be considered fully viewed.
onComplete	Function	undefined	Callback function executed when the element meets the viewability criteria.
onError	Function	undefined	Callback function executed when something wrong.

Methods

Method	Description
start()	Starts tracking if it hasn't already started.
stop()	Stops tracking and disconnects the observer.

Example: Manually Starting Tracking

const tracker = new Viewability("target", { autostart: false });
tracker.onComplete = () => console.log("Element fully viewed!");
tracker.onError = (err) => console.error(err.message);
tracker.start();

Example: Stopping Tracking

tracker.stop();

Browser Support

Viewability.js relies on the IntersectionObserver and MutationObserver API, which are supported in all modern browsers. For older browsers (e.g., Internet Explorer), a polyfill may be required.

Contributing

I would greatly appreciate any contributions to make this project better. Please make sure to follow the below guidelines before getting your hands dirty.

• Fork the repository
• Create your branch (git checkout -b my-branch)
• Commit any changes to your branch
• Push your changes to your remote branch
• Open a pull request

License

Copyright Andrea Fassina, Licensed under MIT.