Viewability tracker used to measure whether a DOM elements is actually seen by users
npm install viewability.jsIntersectionObserver 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.
:star: Star me on GitHub — it motivates me a lot!
isVisible option is enabled (by default), the library performs additional checks to ensure an element is not just in the viewport, but actually visible:
coverageThreshold (value greater than 0 and up to 1).
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();
``