useIntersectionObserver

Layout & observers

A powerful React hook for observing element visibility using the Intersection Observer API

Install

$ npm install @usefy/use-intersection-observer

Quick start

useIntersectionObserver.tsx

import { useIntersectionObserver } from "@usefy/use-intersection-observer";

function MyComponent() {
  const { ref, inView, entry } = useIntersectionObserver();

  return <div ref={ref}>{inView ? "👁️ Visible!" : "👻 Not visible"}</div>;
}

API reference

`useIntersectionObserver(options?)`

A hook that observes element visibility using the Intersection Observer API.

Parameters

Parameter	Type	Description
`options`	`UseIntersectionObserverOptions`	Optional configuration object

Options

Option	Type	Default	Description
`threshold`	`number \| number[]`	`0`	Visibility ratio(s) that trigger updates (0.0 to 1.0). Updates occur when crossing these boundaries
`root`	`Element \| Document \| null`	`null`	Root element for intersection (null = viewport)
`rootMargin`	`string`	`"0px"`	Margin around root (CSS margin syntax). Positive expands, negative shrinks detection area
`triggerOnce`	`boolean`	`false`	Stop observing after element first becomes visible
`enabled`	`boolean`	`true`	Enable/disable observer. When false, observer disconnects and stops all updates
`initialIsIntersecting`	`boolean`	`false`	Initial intersection state before first observation (useful for SSR/SSG)
`onChange`	`(entry: IntersectionEntry, inView: boolean) => void`	—	Callback fired when isIntersecting or intersectionRatio changes
`delay`	`number`	`0`	Delay in milliseconds before creating the observer (not individual events)

Returns `UseIntersectionObserverReturn`

Property	Type	Description
`entry`	`IntersectionEntry \| null`	Intersection entry data (null if not yet observed). Updates trigger re-renders
`inView`	`boolean`	Whether the element is currently intersecting (convenience derived from entry)
`ref`	`(node: Element \| null) => void`	Callback ref to attach to the target element you want to observe

`IntersectionEntry`

Extended intersection entry with convenience properties:

Property	Type	Description
`entry`	`IntersectionObserverEntry`	Original native IntersectionObserverEntry from the browser API
`isIntersecting`	`boolean`	Whether target is intersecting with root
`intersectionRatio`	`number`	Ratio of target visible (0.0 to 1.0)
`target`	`Element`	The observed DOM element
`boundingClientRect`	`DOMRectReadOnly`	Target element's bounding box relative to viewport
`intersectionRect`	`DOMRectReadOnly`	Visible portion's bounding box (intersection of target and root)
`rootBounds`	`DOMRectReadOnly \| null`	Root element's bounding box (null if root is the viewport)
`time`	`number`	DOMHighResTimeStamp when intersection was recorded

Go deeper

This page is the quick reference. For every example, prop, and edge case, read the full README — or open Storybook to change props live.

Full README →Open in Storybook →