Why?

Why should I use this library if there are small snippets to track DOM elements' visibility?

When those snippets are enough for your project's needs - by all means, use them and don't overcomplicate your implementation.

From my practice those 10-15 lines of code are not sufficient to provide unique impressions, visibility after certain point or percentage visibility. Those are vital things commonly shared between different visibility tracking requirements (such as Google Analytics implementation). Sounds good to be put into a single library and work out of the box.

Why not just use IntersectionObserver?

While this is a promising technology, IntersectionObserver is still experimental and shouldn't be relied on without a polyfill. Sentinel DOM uses VanillaJS under its hood (simple numbers comparison), and doesn't rely on experimental features, which results into vast browser support and reliability. It also has much more simple API than the IO (opinionated).

Why should I add another dependency to my project?

In case you are looking for a reliable, stable and thoroughly tested solution, having Sentinel as a dependency is a small trade off.

This library also comes with a built-in performance optimizations (i.e. conditional tracking) which have proven themselves worthy in the production run.

Install

npm install --save sentinel-dom

Getting started

Import the library in your project:

const Observer = require('sentinel-dom').Observer;

Alternatively, with ES6+:

import { Observer } from 'sentinel-dom';

And declare an Observer:

new Observer({
  targets: document.getElementById('box'),
  snapshots: [
    {
      callback({ DOMElement }) {
        console.log(`${DOMElement} is completely visible`);
      }
    },
    {
      thresholdY: 25,
      callback({ DOMElement }) {
        console.log(`At least 25% of ${DOMElement} height is visible`);
      }
    }
  ]
});

That's it! Sentinel will now track the provided targets matching those snapshots using a performant, omni-directional tracking algorithm.

Options and featues

There is much more to that. Thresholds, offsets, bleeding edges, manual tracking and much more can be configured at your will, whenever you need it.

Learn more about all available options and features in the Official documentation.

Concept

The main concept behind Sentinel is an ability to take multiple tracking attempts of the provided target(s) at the same time. Those attempts are refered to as snapshots and allow you to define different tracking logic against the same targets/bounds.

Learn more how Sentinel works under the hood from the Developer documentation.

Contribution

Feel free to submit an issue or a pull request to make this library even better. Make sure to read the Contribution guide to ensure unified workflow and quality of the repository. Thank you!