@adoratorio/medusa v2.1.0

Medusa

A simple utility to easy handle multiple IntersectionObserver

Installation

# Install package
npm install @adoratorio/medusa

Browser Compatibility

If you want to support the browsers that don't support the Itersection Observer you have to change your idea or, at least, don't use this utils 🥳.

Usage

Since this package has a pkg.module field, it's highly recommended to import it as an ES6 module with some bundlers like webpack or rollup:

import Medusa from '@adoratorio/medusa';

const medusa = new Medusa(/* { ...medusaOptions  } */);

Available options

MedusaOptions

Definition:

Medusa observer

When you want to add a new observer in Medusa, you have to create a new configuration object with a specific structure where only the property id is required.

ObserverConfig interface:

interface ObserverConfig = {
  id : string,
  viewport : null | Document | HTMLElement,
  nodes : Array<Element>,
  threshold : number,
  offsets: string,
  emitGlobal : boolean,
  emitByNode : boolean,
  mode : MODE,
  callback : Function,
};

Definition:

Properties

observers

You can access to all the observers added by the property observers.

Medusa.observers : Map<string, InternalObserver>;

If you want a specific InternalObserver you can do like this:

Medusa.observers.get('observerId');

ObserverConfig interface:

interface InternalObserver = {
  id : string,
  observerInstance : null | IntersectionObserver,
  observedNodes : Map<number, MedusaElement>,
  emitGlobal : boolean,
  emitByNode : boolean,
  mode : MODE,
  callback : Function,
};

InternalObserver definition:

Methods

addObserver

To add a new observer you have to create a specific object with the ObserverConfig structure and then you have to pass it to the method.

Medusa.addObserver(configurations : Array<PartialObserverConfig> | PartialObserverConfig);

removeObserver

To remove a specific observer you have to know its id and then pass it to the method.

Medusa.removeObserver('observerId' : string);

clearObserver

Call it if you want to remove all observed nodes from a specific observer providing its id to the method.

Medusa.clearObserver('observerId' : string);

clearAllObservers

Call it if you want to remove all observed nodes from all observers.

Medusa.clearAllObservers();

observe

To observe single node or an array of nodes, you have to pass the observerId of the observer already created and the node/nodes that you want to add.

Medusa.observe('observerId' : string, elToAdd : Element | Array<Element>);

unobserve

To unobserve a single node or an array of nodes, you have to pass the observerId of the observer and the node/nodes that you want to remove.

Medusa.unobserve('observerId' : string, elToRemove : Element | Array<Element>);

Events

When a new Observer is created you can choose if Medusa can emit an event on two different targets:

Argument details:

event.detail = {
  node : Element, // node observed that intersect the viewport previously defined
  isIn : boolean, // if the element observed is in viewport or not
  entry : IntersectionObserverEntry, // the IntersectionObserver entry
}