React IntersectionObserver Hook

Ever tried to implement lazy loading or scroll animations and ended up wrestling with scroll event listeners and manual viewport calculations? You know the drill—measuring element positions, calculating visibility percentages, dealing with performance issues from constant scroll events. This free open source React useIntersectionObserver custom hook handles all that visibility detection complexity so you can focus on building smooth user experiences instead of reinventing intersection math in your React applications.

useIntersectionObserver showcase

Efficient element visibility tracking with native browser APIs:

"use client";import * as React from "react";import { toast } from "sonner";import { Badge } from "@/components/ui/badge";import { Label } from "@/components/ui/label";import { useIntersectionObserver } from "@/components/ui/shadcn-io/use-intersection-observer";export default function UseIntersectionObserverDemo() {  const { isIntersecting, ref } = useIntersectionObserver({    threshold: 0.5,    freezeOnceVisible: false,  });  React.useEffect(() => {    if (isIntersecting) {      toast.success("Element visible! 👁️", {        description: "50% of element is in viewport",      });    }  }, [isIntersecting]);  return (    <div className="p-6 max-w-sm mx-auto space-y-6">      {/* Header */}      <div className="text-center space-y-2">        <h3 className="text-lg font-semibold">Intersection Observer Demo</h3>        <p className="text-sm text-muted-foreground">Viewport visibility detection</p>      </div>            {/* Visibility Status */}      <div className="space-y-2">        <Label className="text-sm font-medium">Visibility State</Label>        <div className="bg-muted rounded p-3 min-h-[48px] flex items-center justify-center">          <Badge variant={isIntersecting ? "default" : "secondary"} className="text-lg px-4 py-2">            {isIntersecting ? "Visible" : "Not Visible"}          </Badge>        </div>      </div>      {/* Scrollable Container */}      <div className="space-y-2">        <Label className="text-sm font-medium">Scroll Area</Label>        <div className="h-32 overflow-y-auto border rounded bg-muted">          <div className="h-24 flex items-center justify-center text-xs text-muted-foreground">            ↓ Scroll down          </div>                    {/* Target Element */}          <div             ref={ref}            className={`mx-3 my-4 p-4 rounded border-2 border-dashed text-center transition-colors ${              isIntersecting                ? "border-primary bg-primary/10 dark:bg-primary/20"                 : "border-gray-300 bg-white dark:bg-gray-800"            }`}          >            <p className="text-sm font-medium">              {isIntersecting ? "✨ In view!" : "📍 Target"}            </p>          </div>          <div className="h-24 flex items-center justify-center text-xs text-muted-foreground">            ↑ Scroll up          </div>        </div>      </div>      {/* Instructions */}      <div className="text-center min-h-[20px] flex items-center justify-center">        <div className="text-xs text-muted-foreground">          Scroll to trigger visibility detection at 50%        </div>      </div>    </div>  );}

import * as React from "react"import { Slot } from "@radix-ui/react-slot"import { cva, type VariantProps } from "class-variance-authority"import { cn } from "@/lib/utils"const badgeVariants = cva(  "inline-flex items-center justify-center rounded-md border px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 [&>svg]:size-3 gap-1 [&>svg]:pointer-events-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive transition-[color,box-shadow] overflow-hidden",  {    variants: {      variant: {        default:          "border-transparent bg-primary text-primary-foreground [a&]:hover:bg-primary/90",        secondary:          "border-transparent bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90",        destructive:          "border-transparent bg-destructive text-white [a&]:hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",        outline:          "text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground",      },    },    defaultVariants: {      variant: "default",    },  })function Badge({  className,  variant,  asChild = false,  ...props}: React.ComponentProps<"span"> &  VariantProps<typeof badgeVariants> & { asChild?: boolean }) {  const Comp = asChild ? Slot : "span"  return (    <Comp      data-slot="badge"      className={cn(badgeVariants({ variant }), className)}      {...props}    />  )}export { Badge, badgeVariants }

This free open source React hook simplifies viewport intersection detection with TypeScript support for modern JavaScript applications. Whether you're building lazy loading systems, scroll animations, or analytics tracking in your Next.js projects, this React hook keeps your visibility logic performant.

Installation

npx shadcn@latest add https://www.shadcn.io/registry/use-intersection-observer.json

npx shadcn@latest add https://www.shadcn.io/registry/use-intersection-observer.json

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/use-intersection-observer.json

bunx shadcn@latest add https://www.shadcn.io/registry/use-intersection-observer.json

Why most visibility detection implementations suck

Look, you could keep writing scroll event handlers and calculating element positions manually. But then you hit the performance wall—scroll events fire constantly, getBoundingClientRect is expensive, and you need to throttle everything to keep things smooth.

Most developers use scroll listeners with getBoundingClientRect() calculations, causing performance bottlenecks in React applications. Or they forget to throttle scroll events, leading to janky animations and poor user experience. Some skip cleanup entirely and wonder why their scroll handlers accumulate over time in TypeScript components.

This React hook uses the native Intersection Observer API under the hood in Next.js projects, which is specifically designed for efficient visibility tracking. The browser handles all the optimization, so you get smooth performance without the complexity.

Plus it handles all the edge cases—cleanup on unmount, browser compatibility, threshold configurations, freeze-once-visible behavior. No more memory leaks or janky scroll performance in JavaScript applications.

This free open source React hook manages efficient visibility detection while you focus on building features. Whether you're creating React applications, Next.js dashboards, or TypeScript components, reliable intersection tracking keeps your JavaScript development performant.

Features

• Intersection Observer API with native browser support and automatic cleanup in React applications
• Configurable thresholds supporting single values or arrays for precise detection in TypeScript components
• Freeze on visible option to lock state once element becomes visible in Next.js projects
• Custom root elements allowing observation relative to any container in JavaScript development
• TypeScript support with complete type definitions and flexible destructuring for React frameworks
• Performance optimized using efficient native browser APIs with minimal overhead in modern applications
• Free open source designed for modern React development workflows

When you'll actually use this

Real talk—this isn't for every visibility check in React applications. Simple show/hide logic often works fine with CSS or basic state. But when you need performance-critical visibility detection or complex threshold logic, this React hook delivers in Next.js projects.

Perfect for:

• Lazy loading - Images, videos, and content that loads when visible built with TypeScript
• Scroll animations - Trigger effects when elements enter the viewport using React patterns
• Analytics tracking - Monitor content exposure and engagement metrics in JavaScript applications
• Infinite scroll - Detect when users reach the bottom of lists in React components
• Performance optimization - Defer expensive operations until needed in Next.js applications
• Progress indicators - Track reading progress and section visibility using TypeScript validation

API Reference

useIntersectionObserver

Return Value (Supports both tuple and object destructuring)

Common gotchas

Ref attachment requirement: The React hook won't work until you assign the ref to an actual element in your render in TypeScript components. Make sure the element exists and has dimensions.

Modern browser API limitation: Intersection Observer is supported in all modern browsers but won't work in Internet Explorer in React applications. The hook handles graceful degradation for older browsers.

Threshold percentage meanings: 0 means any pixel visible, 1 means completely visible in Next.js projects. Arrays let you track multiple visibility levels for complex animations.

Freeze behavior permanence: Once freezeOnceVisible is true and the element becomes visible, it stays visible even if scrolled away in JavaScript applications—perfect for one-time animations but can be confusing for debugging.

Root margin CSS syntax: rootMargin uses CSS margin syntax ("10px 20px") not JavaScript object syntax in React development. Incorrect syntax will cause unexpected behavior.

Observer instance sharing: Multiple elements with identical options share the same observer instance for performance in TypeScript projects, but different options create separate observers.

Related hooks you will also like

Questions you might have