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:

$3

``sh
npm install viewability.js
`

$3

`html

`

Usage

$3

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:

`js
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");
`

$3

`js
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);
`

$3

| 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. |

$3

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

$3

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

$3

`js
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.

1. Fork the repository
2. Create your branch (git checkout -b my-branch)
3. Commit any changes to your branch
4. Push your changes to your remote branch
5. Open a pull request

License

Copyright Andrea Fassina, Licensed under MIT.