1.0.0 • Public • Published

    Observer Registry


    Observer Registry is a lightweight (1.8KB or 709B gzip!) library to make interacting with the Intersection Observer API a little more pleasant by allowing you to specify callbacks for each element you are observer. ObserverRegistry will handle instantiating any] IntersectionObservers while using the fewest instances to accomplish your observation needs.


    Install the package from npm:

    npm install observer-registry


    The first step to using ObserverRegistry is creating an instance. You should really only ever need once instance of the ObserverRegistry, it will maintain any and all instances of IntersectionObserver in order to give you the desired results.

    Observing an element

    Observing an element is simple, you just pass the element and a callback to be notified when it changes.

    const element = document.getElementById('my-element')
    observer.addElement(element, event => alert('element visibility changed!'))

    You can pass as many elements into an instance of ObserverRegistry as you want:

    const callback = () => alert('An element has been seen!')
    const header = document.getElementById('header')
    const menu = document.getElementById('menu')
    const body = document.getElementById('body')
    const footnote = document.getElementById('footnote')
    const footer = document.getElementById('footer')
    // Or call addElement as many times as you want (with chaining)
    observer.addElement(header, callback).addElement(menu, callback)
    // You can register an array of elements
    observer.addElement([body footnote, footer], callback)
    // Or with a NodeList
    observer.addElement(document.querySelectorAll('.pictures'), callback)

    Removing an element

    To stop watching for intersection events on an element simply remove it.


    Observe an element with custom margins

    The addElement method accepts a third argument options. Included in the list of available options are the three options provided by the native IntersectionObserver class root, rootMargin, and threshold. For a full list of options see the table below.

    observer.addElement(element, () => alert('Using a margin'), {
        rootMargin: '-100px'

    Observe an element with custom root

    const element = document.getElementById('my-element')
    observer.addElement(element, () => `element within margin!`, {
        root: document.getElementById('my-scroll-window')

    Observe only once

    Perfect for times when you only need to know when an item comes into view, you can choose to automatically remove an element after its first observed event. This is ideal for things like lazy loading images or performing entrance animations on scroll where you don't need the effect to be repeated.

    observer.addElement(element, () => alert('do this once!'), { once: true })

    addElement options

    The third argument of addElement can be an options object.

    Key Description Default Value
    once Only trigger the callback once false
    root IntersectionObserver root null (binds to the viewport)
    rootMargin IntersectionObserver rootMargin 0px
    threshold IntersectionObserver threshold 0.0


    There are a few known limitations, happy to accept pull requests for these or any others you might find.

    One instance of each element

    Currently it is only possible for any given element to be observed by one IntersectionObserver meaning that if the same element is registered twice, the first registered callback will be called.

    const element = document.getElementById('my-element')
    observer.addElement(element, event => alert(`element is${event.visibility ? ' ' : ' not '}visible`))
    observer.addElement(element, event => alert('do some other activity'))
    // alert(`element is visible`)

    IntersectionObserver support

    Truth of the matter is that IntersectionObserver does not have spectacular browser support (lookin' at you Safari). So depending on your needs, this utility may require a polyfill. The good news is that w3c has provided one.


    npm i observer-registry

    DownloadsWeekly Downloads






    Unpacked Size

    14.6 kB

    Total Files


    Last publish


    • justin-schroeder