Interserver

IntersectionObserver simplified

Interserver is an easy way to check if a dom element is intersecting the viewport.

Features

• Tiny (~1kb minified)
• TypeScript ready
• Framework agnostic (easily integrate Interserver with your favourite framework)
• React companion package (interserver-react)
• Svelte companion package (interserver-svelte)

Installation

With yarn:

yarn add interserver

With npm:

npm install --save interserver

Usage

import interserver from "interserver";

const container = document.querySelector("#container");

// The handler is fired whenever `isIntersecting` changes
function handleChange(isIntersecting) {
  if (isIntersecting) {
    console.log("Container is visible!")
  }
}

const unobserve = interserver(container, handleChange);

// Cancel observation after five seconds
setTimeout(unobserve, 5000);

If you want to run cancel the observation after the first time, the container is visible, you can pass the once option to interserver:

import interserver from "interserver";

const container = document.querySelector("#container");

function handleChange(isIntersecting) {
  if (isIntersecting) {
    console.log("I will run only once.")
  }
}

interserver(container, handleChange, { once: true });

You can also specify margins around the element (top, right, bottom, left), so that the handler will fire when the container is the specified margin away from the viewport:

import interserver from "interserver";

const container = document.querySelector("#container");

function handleChange(isIntersecting) {
  if (isIntersecting) {
    console.log("I will run when I am 20px away from the viewport.")
  }
}

interserver(
  container,
  handleChange,
  { top: 20, right: 20, bottom: 20, left: 20 },
);

API

/**
 * Observe an element and invoke a callback, when it is intersecting the viewport.
 *
 * @param container The DOM element that is being observed.
 * @param onChange The callback handler,
 * that will be called when the `isIntersecting` state changes.
 * @param options The observer options,
 * consisting of offset margins for the container (`top`, `right`, `bottom`, `left`)
 * and `once`. With `once` set to `true`,
 * observing stops after the element is first intersecting.
 *
 * @returns The `unobserve` function. Observation is canceled, when it is called.
 */
export type Interserver = (
  container: Element,
  onChange: InterserverOnChange,
  options?: InterserverOptions,
) => InterserverUnsubscribe;

/**
 * The callback handler, that will be called when the `isIntersecting` state changes.
 */
export type InterserverOnChange = (isIntersecting: boolean) => void;

/**
 * The observer options,
 * consisting of offset margins for the container (`top`, `right`, `bottom`, `left`)
 * and `once`.
 * With `once` set to `true`, observing stops after the element is first intersecting.
 */
export interface InterserverOptions {
  top?: number;
  right?: number;
  bottom?: number;
  left?: number;
  once?: boolean;
}

/**
 * The `unsubscribe` function returned from a call to `interserver`.
 * It should be called, when the observation is not needed any more,
 * to prevent memory leaks.
 * If `InterserverOptions.once` is set to true, the `unsubscribe`
 * function will be called internally.
 */
export type InterserverUnsubscribe = () => void;

License

MIT