intersectr

An esay-to-use wrapper class over intersection observer API.

You can find a simple demo here.

Getting started

Installation

You just have to import Intersectr.min.js class into your HTML page (you can find it on the dist folder of this repository) :

<script type="text/javascript" src="/path/to/Intersectr.min.js" defer></script>

Intersectr is compatible with IE11+ (it includes a polyfill of intersection-observer API) and is supported by all modern browsers.

Basic usage

And you can use Intersectr class like so :

document.addEventListener('DOMContentLoaded', _ => {
 
    const intersectr = new Intersectr()
 
    intersectr.intersect('.my-item', (intersecting, entry) => {
        if (intersecting) {
            entry.target.classList.add('intersected')
            entry.unobserve(true)
        }
    })
 
})

And.. That's it ! Easy, isn't it ? :)

API

Intersectr comes with a very simple API.

observe

Unobserves the HTML element defined by the target parameter, and triggers the callback when its visible (depends on the global threshold ratio(s)).

Intersectr.observe(
    target: Element|String, 
    callback: Function(entry: IntersectionObserverEntry)
): Intersectr

Example :

intersectr.observe('.my-item', entry => {
    if (entry.isIntersecting) {
        entry.target.classList.add('intersected')
        entry.unobserve(true)
    }
})

unobserve

Unobserves the HTML element defined by the target parameter. It deletes observables callbacks if soft parameter is false, does nothing otehrwise (useful with the refresh() method).

Intersectr.unobserve(
    target: Element|String, 
    soft: Boolean = true
): Intersectr

Example :

intersectr.unobserve('.my-item', true)

intersect

Observes the HTML element defined by the target parameter, and triggers the callback when its visible. The main difference with the observe() method is that the callback function will expose intersecting parameter which is true if teh element is intersecting, false otherwise (depends on the global threshold ratio(s)).

Intersectr.intersect(
    target: Element|String, 
    callback: Function(intersecting: Boolean, entry: IntersectionObserverEntry)
): Intersectr

Example :

intersectr.intersect('.my-item', (intersecting, entry) => {
    if (intersecting) {
        entry.target.classList.add('intersected')
        entry.unobserve(true)
    }
})

intersectFrom

Intersecting from an intersection ratio.

Intersectr.intersectFrom(
    target: Element|String, 
    ratio: Number, 
    callback: Function(intersecting: Boolean, entry: IntersectionObserverEntry)
): Intersectr

Example :

intersectr.intersectFrom('.my-item', .3, (intersecting, entry) => {
    if (intersecting) {
        entry.target.classList.add('intersected')
        entry.unobserve(true)
    }
})

intersectUntil

Intersecting until an intersection ratio.

Intersectr.intersectUntil(
    target: Element|String, 
    ratio: Number, 
    callback: Function(intersecting: Boolean, entry: IntersectionObserverEntry)
): Intersectr

Example :

intersectr.intersectUntil('.my-item', .8, (intersecting, entry) => {
    if (intersecting) {
        entry.target.classList.add('intersected')
        entry.unobserve(true)
    }
})

intersectBetween

Intersecting between intersection ratios.

Intersectr.intersectBetween(
    target: Element|String, 
    ratios: Number[], 
    callback: Function(intersecting: Boolean, entry: IntersectionObserverEntry)
): Intersectr

Example :

intersectr.intersectBetween('.my-item', [.3, .8], (intersecting, entry) => {
    if (intersecting) {
        entry.target.classList.add('intersected')
        entry.unobserve(true)
    }
})

refresh

Refresh all observers. Useful to observe again 'soft' unobserved entries.

Intersectr.refresh(): Intersectr

Example :

intersectr.intersectBetween('.my-item', [.3, .8], (intersecting, entry) => {
    if (intersecting) {
        entry.target.classList.add('intersected')
        entry.unobserve(true) // soft unobserve
    }
})
 
// ...
 
intersectr.refresh() // will observe again the 'soft' unobserved entry above

destroy

Intersectr.destroy(): void