inView

inView detects when elements enter and leave the viewport.

inView("#carousel li", (element) => {
  animate(element, { opacity: 1 })
})

Detecting when an element is in view can help creating effects like:

• Animating elements when they scroll into and out of view.

• Deactivating animations when they're no longer visible.

• Lazy-loading content.

• Automatically start/stop videos.

inView function is built on the browser's native Intersection Observer API for the best possible performance (all calculations happen off the main JavaScript thread) and a tiny filesize (just 0.5kb).

Usage

Import from "motion":

import { inView } from "motion"

inView can accept either a selector, Element, or array of Elements.

// Selector
inView("section", callback)

// Element
const box = document.getElementById("box")
inView(box, callback)

By default, the provided callback will fire just once, when the element first enters the viewport.

inView(element, () => {
  console.log("Element has entered the viewport")
})

This callback is provided the matched element and an IntersectionObserverEntry object which contains information on the intersection.

inView("a", (element, info) => {
  console.log("The link ", element, " has entered the viewport")
})

Leaving the viewport

A function returned from this callback will fire when the element leaves the viewport.

inView(element,
  (element, enterInfo) => {
    const animation = animate(element, { opacity: 1 })
    
    // This will fire when the element leaves the viewport
    return (leaveInfo) => animation.stop()
  }
)

Additionally, the gesture will also continue to fire as the element enters/leaves the viewport.

Change viewport

By default, inView detects when the provided element(s) enter/leave the default viewport: The browser window.

But it can also detect when the element(s) enter/leave the viewport of a scrollable parent element, by passing that element to the root option:

const carousel = document.querySelector("#carousel")

inView("#carousel li", callback, { root: carousel })

Stop detection

inView returns a function that, when fired, will stop viewport detection.

const stop = inView(element, callback)

stop()

Options

root

Default: window

If provided, inView will use the root element's viewport to detect whether the target elements are in view. Otherwise defaults to the browser window.

const carousel = document.querySelector("#carousel")

inView("#carousel li", callback, { root: carousel })

margin

Default: 0

One or more margins to apply to the viewport. This will extend or contract the point at which the element is considered inside or outside the viewport.

margin can be defined in pixels or percentages. It can accept up to four values in the order of top/right/bottom/left.

inView(element, callback, { margin: "0px 100px 0px 0px" })

Positive values extend the viewport boundaries beyond the root whereas negative values will pull it in.

Note: For browser security reasons, margin won't take affect within cross-origin iframes unless root is explicitly defined.

amount

Default: "some"

The amount of the target element that needs to be within the viewport boundaries to be considered in view.

This can be defined as "some", for some of the element, or "all", for all of the element.

Additionally, it can be defined as a number proportion between 0 and 1 where 0 is "some" and 1 is "all".