@adoratorio/medusa

A simple utility to easy handle multiple IntersectionObserver

Usage no npm install needed!

<script type="module">
  import adoratorioMedusa from 'https://cdn.skypack.dev/@adoratorio/medusa';
</script>

README

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 API you need to install the IntersectionObserver polyfill.

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({
  targets: [{ /* ...targetOptions */ }],
  // ...medusaOptions
});

If you are not using any bundlers, you can just load the UMD bundle:

<script src="/medusa/umd/index.js"></script>

<script>
  var medusa = window.Medusa({
    targets: [{ /* ...targetOptions */ }],
    // ...medusaOptions
  });
</script>

Available options

MedusaOptions

Definition:

parameter type default description
targets Array<MedusaTarget> [] Array to fill with MedusaTarget
debug boolean true Set it to false if you don't want messages in console

MedusaTarget

Target interface:

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

Definition:

parameter type default description
id string required The Observer identifier, usefull in case you add multiple observer.
viewport HTMLElement null The element that is used as the viewport for checking visibility of the target.
nodes Array<HTMLElement> [] All nodes you want to observe.
threshold number 0 numbers which indicate at what percentage of the target's visibility, a float value between (0, 1).
You can use:
• a float number
• Medusa.THRESHOLD.BEARLY (0.0)
• Medusa.THRESHOLD.HALF (0.5)
• Medusa.THRESHOLD.FULL (1.0)
offsets string '0px 0px 0px 0px' Margin around the root. Can have values similar to the CSS margin property
emitGlobal boolean false If it's true, Medusa emit the intersection custom event on the window
emitByNode boolean false If it's true, Medusa emit the intersection custom event on the node that intersect the viewport
callback function (entry, observer) => {} A function that is executed whenever an element intersect the viewport threshold that you set in the options. You have the access to the single entry and the istance of the observer.
Mode string Meduse.MODE.DEFAULT Parameter that permit to change how many time the callback is execute.
You can use:
• Medusa.MODE.DEFAULT or 'default': trigger the callback every time the element intersect the viewport threshold.
Medusa.MODE.ONCE or 'once': trigger the callback the only once.
Medusa.MODE.BYPIXELS or 'byPixel': trigger the callback every pixel when the element observed is in viewport.
autoremove boolean false If it's true and the mode is 'once' , Medusa autoremove the target once all nodes callback are triggered

APIs

getTargetFromId()

Get specific target passing its id to the method.

Medusa.getTargetFromId('targetId' : string);

addTarget()

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

Medusa.addTarget(target : Array<Target> | Target);

removeTarget()

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

Medusa.removeTarget('targetId' : string);

clearTarget()

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

Medusa.clearTarget('targetId' : string);

clearAllTargets()

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

Medusa.clearAllTargets();

pushToTarget()

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

Medusa.pushToTarget('targetId' : string, elToAdd : HTMLElement | Array<HTMLElement>);

pullFromTarget()

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

Medusa.pullFromTarget('targetId' : string, elToRemove : HTMLElement | Array<HTMLElement>);