What you get Copy Chapter

• Shared observer instances. Targets that use the same options share one IntersectionObserver, so observing hundreds of elements is cheap.
• Types in the package. Hooks, components, options, and entries are typed. There is no @types package to install.
• Two test layers. react-intersection-observer/test-utils drives deterministic transitions, and Browser Mode runs the browser's own observer.
• Separate entry points. Import only useInView and the rest is tree shaken away, around 1.15kB gzipped.

Where to go next Copy Chapter

• Core APIs covers the full contracts and return values.
• Observer options covers thresholds, margins, and scroll containers.
• Recipes builds lazy loading, reveals, impressions, and infinite lists.
• Testing covers verification, and SSR and fallbacks covers server rendering.

Apps Docs Docs Testing Index (`apps/docs/docs/testing/index.mdx`) Copy Section

title: Testing sidebar: order: 1 Copy Chapter

Intersection Observer tests fall into two groups. Pick the layer first, then follow the guide for that kind of test.

Choose a test layer Copy Chapter

The two work together. Browser Mode verifies browser integration, and the mock produces deterministic observer signals. Keep the global mock setup out of native browser tests.

Organize a mixed suite Copy Chapter

Give each layer its own named project so the DOM mock never leaks into native browser tests:

Both guides show the configuration for their own project.

Apps Docs Evals.Yaml (`apps/docs/evals.yaml`) Copy Section

questions:

• id: install-and-observe-element
  question: How do I install the package and observe an element?
  expected:

  • Install the react-intersection-observer package.
  • Import and call useInView.
  • Attach the returned ref to the element that should be observed.
  • inView changes when the element crosses the configured threshold.
  • entry is undefined until an observer notification has been accepted.
    routes:
  • /

• id: choose-public-api
  question: Which API should I use for state, effects, or component composition?
  expected:

  • Use useInView when visibility affects rendered React state.
  • Use useOnInView for callbacks such as analytics or prefetching without a hook-owned state update.
  • Use InView when render props or a generated wrapper fit the composition.
    routes:
  • /api/core-apis

• id: configure-visibility-trigger
  question: How can I control when an element counts as visible?
  expected:

  • threshold sets the visible ratio required for inView to become true.
  • rootMargin expands or contracts the root bounds so work can start earlier or later.
  • scrollMargin adjusts clipping across nested scroll containers.
    routes:
  • /api/configuration

• id: observe-inside-scroll-container
  question: How do I observe an element inside a custom scroll container?
  expected:

  • The viewport is the default root.
  • Pass the ancestor scroll container as root.
  • The root must be an ancestor of the observed target.
  • Keep the root in state so the hook receives it after React assigns the element.
    routes:
  • /api/configuration

• id: stop-or-pause-observation
  question: How do I stop after the first view or pause observation?
  expected:

  • triggerOnce stops observing after the first accepted true transition.
  • skip temporarily disables observation while preserving the current state.
  • onChange is available on useInView and InView.
  • Use useOnInView when a callback is the only result needed and no hook-owned state update is wanted.
    routes:
  • /api/configuration

• id: deploy-ssr-app-safely
  question: What should I decide before deploying an SSR app?
  expected:

  • initialInView controls the state rendered before the first observer notification.
  • initialInView does not create an observer or guarantee that the target is visible.
  • Hydration attaches the observer after the browser takes over.
  • A client without IntersectionObserver throws unless a fallback is configured.
  • fallbackInView sets a local fallback, while defaultFallbackInView sets a global policy.
    routes:
  • /guides/ssr

• id: enable-observer-v2
  question: How do I detect whether intersecting content is actually visible?
  expected:

  • Enable trackVisibility and read entry.isVisible.
  • Set delay to at least 100 milliseconds.
  • Observer v2 support is narrower than the original Intersection Observer API.
  • When isVisible is unsupported, the package approximates it with the calculated intersection state.
  • Real occlusion must be verified in a supported browser.
    routes:
  • /guides/intersection-observer-v2

• id: test-native-browser-behavior
  question: How should I test real scrolling and observer behavior?
  expected:

  • Use Vitest Browser Mode when behavior depends on real layout, scrolling, focus, or native IntersectionObserver delivery.
  • Run browser tests in a Chromium project and keep them separate from DOM-emulated tests that use the package mock.
  • Native IntersectionObserver delivery is asynchronous, so assertions should wait for the update.
  • Do not load react-intersection-observer/test-utils globally in the Browser Mode project because it replaces the native API.
    routes:
  • /testing/browser-mode

• id: mock-intersection-transitions
  question: How do I test intersection transitions deterministically?
  expected:

  • Import utilities from react-intersection-observer/test-utils in a DOM-capable test environment.
  • Use mockAllIsIntersecting or mockIsIntersecting to deliver controlled observer entries.
  • Boolean values simulate entering or leaving, while numbers cross configured thresholds.
  • The mock tests callbacks and state transitions but does not prove physical layout or native browser geometry.
  • Reset observed elements and mock calls between tests.
    routes:
  • /testing/mocking-intersections

• id: build-accessible-infinite-scroll
  question: How do I build accessible infinite scrolling?
  expected:

  • Observe a sentinel at the end of the list.
  • Use skip while loading, after the last page, or on error to prevent duplicate requests.
  • rootMargin can begin loading before the sentinel reaches the viewport.
  • Keep a manual Load more action for keyboard and assistive-technology users.
  • Provide a retry boundary instead of making scrolling the only way to fetch content.
    routes:
  • /guides/recipes

Apps Docs Package.Json (`apps/docs/package.json`) Copy Section

{
"name": "docs",
"private": true,
"scripts": {
"dev": "blume dev",
"build": "ASTRO_TELEMETRY_DISABLED=1 blume build",
"lint": "biome check .",
"typecheck": "ASTRO_TELEMETRY_DISABLED=1 blume check",
"validate": "ASTRO_TELEMETRY_DISABLED=1 blume validate",
"og": "node scripts/generate-og.mjs"
},
"dependencies": {
"react": "^19.2.8",
"react-dom": "^19.2.8",
"react-intersection-observer": "workspace:*"
},
"devDependencies": {
"@biomejs/biome": "^2.5.6",
"blume": "^2.2.3",
"takumi-js": "^2.5.4"
}
}

Apps Docs Docs Api Configuration (`apps/docs/docs/api/configuration.mdx`) Copy Section

title: Observer options Copy Chapter

Most components only need to decide when an element counts as visible, where to observe it, and what happens after the first notification. Those three sections come first. The full option reference is at the end.

Attach ref to the target. The browser viewport is the root by default. An intersection happens when the target crosses that root's bounds, and thresholds and margins move where that line sits.

Choose when it counts as visible Copy Chapter

Use threshold when the amount of visible content matters. A threshold of 0.5 means the target must be at least half visible before inView becomes true:

useInView({ threshold: 0.5 });

Use rootMargin to start earlier or later than the target's actual edge. This is useful for preloading:

useInView({
  rootMargin: "200px 0px",
  triggerOnce: true,
});

scrollMargin grows or shrinks the clipping rectangles of scroll containers nested inside the root.

Choose where to observe Copy Chapter

Leave root out, or set it to null, to observe against the browser viewport. To observe inside a scroll container, pass that container as root. It has to be an ancestor of the target, and it needs a bounded scrolling area. Keep it in state so the hook gets the element after React assigns it:

import { useState } from "react";
import { useInView } from "react-intersection-observer";

export function ScrollArea() {
  const [root, setRoot] = useState<HTMLDivElement | null>(null);
  const { ref, inView } = useInView({ root });

  return (
    <div
      ref={setRoot}
      style={{ blockSize: 240, overflowY: "auto" }}
    >
      <div style={{ blockSize: 220 }} />
      <article ref={ref}>
        {inView ? "Visible in this container" : "Waiting"}
      </article>
      <div style={{ blockSize: 220 }} />
    </div>
  );
}

When an inner scroller clips the target, add scrollMargin, as in useInView({ root, scrollMargin: "80px 0px" }). Watch out for the things that quietly change what the browser considers visible: invalid margin syntax, thresholds outside 0 to 1, iframes, and custom roots.

:::note[Verify configuration]
Test real layout, scrolling, and geometry in Vitest Browser Mode. To cross a configured threshold without depending on layout, use a deterministic mock. See Mock intersections.
:::

Stop or pause observation Copy Chapter

triggerOnce stops observing after the first accepted true transition. skip disables observation and keeps the current state.

Use onChange with useInView or `` when you want both React state and a callback. Use useOnInView when the callback is all you need.

const { ref, inView } = useInView({
  triggerOnce: true,
  skip: isSaving,
  onChange(nextInView, entry) {
    console.log(nextInView, entry.target);
  },
});

onChange runs alongside the state update.

Initial, server, and unsupported-client state Copy Chapter

initialInView sets the state before any observer reports. fallbackInView sets a value only when the client has no IntersectionObserver, and defaultFallbackInView sets that value for the whole application.

Both affect server rendering and unsupported browsers. Decide the policy once in SSR and fallbacks instead of spreading it across individual components.

Option reference Copy Chapter

The observation options work with all three APIs. onChange, initialInView, and fallbackInView only work with useInView and ``.

Experimental v2 options Copy Section

Most applications only need inView, which means the target intersects the root. Set trackVisibility: true when you need Observer v2's entry.isVisible field instead, which also accounts for an intersecting target being covered or filtered. Pair it with a delay of at least 100 milliseconds:

useInView({ trackVisibility: true, delay: 100 });

Browser support for v2 is narrower than for the original API. Read Observer v2 before you base viewability or occlusion decisions on isVisible.

Apps Docs Docs Api Core Apis (`apps/docs/docs/api/core-apis.mdx`) Copy Section

title: Core APIs Copy Chapter

react-intersection-observer exports two hooks and one component. They take the same observer options and differ only in how they hand you the result.

:::note[Initial notification]
All three APIs suppress the observer's first false result. initialInView sets the starting state and changes how that first notification is handled. Every enter and leave transition after it reports both true and false.
:::

There is also a low-level observe function for code that already owns a DOM element.

Common configuration choices Copy Chapter

• Load or reveal once with triggerOnce.
• Start work before the target reaches the viewport with rootMargin.
• Require a meaningful amount of content to be visible with threshold.
• Observe inside a scrolling container with root.
• Use useOnInView for analytics or prefetching that should not create a hook-owned re-render.

`useInView` Copy Chapter

Use useInView when visibility belongs in React state:

import { useInView } from "react-intersection-observer";

export function ArticleSection() {
  const { ref, inView } = useInView();

  return <section ref={ref}>{inView ? "In view" : "Waiting"}</section>;
}

The hook supports both object and tuple destructuring:

const { ref, inView, entry } = useInView();
const [ref, inView, entry] = useInView();

entry is undefined until the first accepted notification. After that it is the latest IntersectionObserverEntry, so read intersectionRatio, boundingClientRect, or target from it when the UI needs geometry.

`onChange` Copy Section

useInView can call onChange alongside its state update:

const { ref, inView } = useInView({
  onChange(nextInView, entry) {
    console.log(entry.target, nextInView);
  },
});

Use useOnInView instead when the callback is the only result you need.

`useOnInView` Copy Chapter

useOnInView returns a ref callback and never updates component state. Use it for analytics, logging, prefetching, and anything else that should not cause a render:

import { useOnInView } from "react-intersection-observer";

export function TrackedCard({ id }: { id: string }) {
  const ref = useOnInView(
    (inView, entry) => {
      if (inView) {
        analytics.track("card_visible", { id, target: entry.target });
      }
    },
    { threshold: 0.5, triggerOnce: true },
  );

  return <article ref={ref}>Card {id}</article>;
}

The callback receives (inView, entry). useOnInView accepts the options that affect observation: root, rootMargin, scrollMargin, threshold, triggerOnce, skip, trackVisibility, and delay. It does not accept onChange, initialInView, or fallbackInView.

`` Copy Chapter

Use render props when the component should receive the ref and visibility state directly:

import { InView } from "react-intersection-observer";

export function RevealCard() {
  return (
    <InView threshold={0.2} triggerOnce>
      {({ ref, inView, entry }) => (
        <article ref={ref} className={inView ? "card visible" : "card"}>
          <h2>Card</h2>
          <p>{entry ? "The observer has reported" : "Waiting"}</p>
        </article>
      )}
    </InView>
  );
}

The render prop receives { ref, inView, entry }. Attach the ref to the element you want to observe.

Plain children Copy Section

Plain children always render. In this form `` creates a wrapper element, forwards any extra HTML props to it, and observes it:

<InView as="section" className="article" onChange={handleChange}>
  <h2>Always-rendered content</h2>
</InView>

Use as to keep the generated wrapper semantic. This form does not forward refs. Use render props or useInView when you need direct control of the observed element, or a ref on a custom component.

Low-level `observe` Copy Chapter

When you already own a DOM element outside React rendering, use the low-level observe function. Keep the cleanup function it returns:

import { observe } from "react-intersection-observer";

const stop = observe(
  element,
  (inView, entry) => {
    console.log(inView, entry.intersectionRatio);
  },
  { threshold: 0.5 },
);

// Call this when the element is no longer relevant.
stop();

Shared behavior Copy Chapter

• triggerOnce stops observing after the first accepted true transition.
• skip disables observation while preserving the current state.
• When an observed node is removed and later replaced, the hook resets to initialInView, unless triggerOnce or skip prevents the reset.
• entry is undefined before the first accepted notification, and again after an observed node resets.

See Configuration for every option and Testing for deterministic observer transitions.

Apps Docs Docs Guides Intersection Observer V2 (`apps/docs/docs/guides/intersection-observer-v2.mdx`) Copy Section

title: Observer v2 sidebar: label: Observer v2 badge: Experimental Copy Chapter

Most applications should stick with the standard inView signal. Intersection Observer v2 adds trackVisibility and entry.isVisible for viewability cases where an intersecting element may be covered by something else or hidden behind a filter.

Enable visibility tracking Copy Chapter

Set trackVisibility: true and a delay of at least 100 milliseconds:

import { useOnInView } from "react-intersection-observer";

declare global {
  interface IntersectionObserverEntry {
    isVisible?: boolean;
  }
}

export function Viewability({ onSeen }: { onSeen: () => void }) {
  const ref = useOnInView(
    (inView, entry) => {
      if (inView && entry.isVisible === true) onSeen();
    },
    {
      trackVisibility: true,
      delay: 100,
      threshold: 0.5,
      triggerOnce: true,
    },
  );

  return <div ref={ref}>Measured content</div>;
}

isVisible is not in TypeScript's IntersectionObserverEntry declaration yet, so add the augmentation once in your application types before reading it. The option works with all three APIs. With useOnInView, read entry.isVisible inside the callback. With ``, read it from the render-prop entry or from onChange.

Support and fallback behavior Copy Chapter

Fewer browsers support v2 than the original API. When a browser has Intersection Observer but no isVisible, this package falls back to v1 and sets entry.isVisible to the calculated intersection state. Treat that value as an approximation there.

Missing isVisible and a missing observer are separate problems. If the whole IntersectionObserver API is unavailable, use fallbackInView or defaultFallbackInView as described in Configuration.

Test it in a real browser Copy Chapter

Verify geometry, clipping, and real occlusion in a real browser. The package mock can drive the v1 fallback branch and your callback, but it cannot cover one element with another, so it can never prove occlusion. In deterministic tests, assert the application behavior you need instead.

Keep the minimum delay in shared configuration so a future browser or package update cannot quietly make the observer invalid.

Apps Docs Docs Guides Recipes (`apps/docs/docs/guides/recipes.mdx`) Copy Section

title: Recipes Copy Chapter

Each recipe states the problem, shows a complete component, and calls out the part that is easiest to get wrong. For the API details behind the examples, see Core APIs and Configuration.

Lazy image loading Copy Chapter

:::tip[Prefer native lazy loading]
Add loading="lazy" to ordinary image elements and the browser defers loading for you, with no observer code.
:::

Reach for the observer when you need a specific preload margin, a custom placeholder, or a loading transition on the component.

import { useInView } from "react-intersection-observer";

type LazyImageProps = {
  src: string;
  alt: string;
  width: number;
  height: number;
};

export function LazyImage({ src, alt, width, height }: LazyImageProps) {
  const { ref, inView } = useInView({
    rootMargin: "200px 0px",
    triggerOnce: true,
  });

  return (
    <div ref={ref} style={{ aspectRatio: `${width} / ${height}` }}>
      {inView ? (
        <img src={src} alt={alt} width={width} height={height} />
      ) : (
        <div aria-hidden="true" className="image-placeholder" />
      )}
    </div>
  );
}

import { useEffect, useState } from "react";
import { useInView } from "react-intersection-observer";

export function Reveal({ children }: { children: React.ReactNode }) {
  const [enhanced, setEnhanced] = useState(false);
  const { ref, inView } = useInView({
    fallbackInView: true,
    threshold: 0.2,
    triggerOnce: true,
  });

  useEffect(() => {
    setEnhanced("IntersectionObserver" in window);
  }, []);

  return (
    <div
      ref={ref}
      className={enhanced && !inView ? "reveal reveal-pending" : "reveal"}
    >
      {children}
    </div>
  );
}

.reveal {
  opacity: 1;
  transform: none;
  transition: opacity 250ms ease, transform 250ms ease;
}

.reveal-pending {
  opacity: 0;
  transform: translateY(1rem);
}

@media (prefers-reduced-motion: reduce) {
  .reveal {
    opacity: 1;
    transform: none;
    transition: none;
  }
}

import { useOnInView } from "react-intersection-observer";

type ImpressionProps = {
  id: string;
  record: (id: string) => void;
};

export function Impression({ id, record }: ImpressionProps) {
  const ref = useOnInView(
    (inView) => {
      if (inView) record(id);
    },
    { threshold: 0.5, triggerOnce: true },
  );

  return <article ref={ref}>Tracked content</article>;
}

/* Detailed source-code truncated for AI context efficiency. */

const { ref, inView } = useInView({
  initialInView: true,
});

const { ref, inView } = useInView({
  fallbackInView: false,
});

import { defaultFallbackInView } from "react-intersection-observer";

defaultFallbackInView(false);

pnpm add -D vitest vitest-browser-react @vitest/browser-playwright playwright
pnpm exec playwright install chromium

// vitest.config.ts
import { playwright } from "@vitest/browser-playwright";
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    include: ["src/**/*.browser.test.{ts,tsx}"],
    browser: {
      enabled: true,
      provider: playwright(),
      instances: [{ browser: "chromium" }],
    },
  },
});

import { render } from "vitest-browser-react";
import { expect, test } from "vitest";
import { useInView } from "react-intersection-observer";

function RevealOnScroll() {
  const [ref, inView] = useInView();

  return (
    <div ref={ref} data-inview={inView} style={{ height: 200 }}>
      Observed target
    </div>
  );
}

test("updates when the target scrolls into the viewport", async () => {
  const screen = await render(
    <>
      <div style={{ height: window.innerHeight }} />
      <RevealOnScroll />
      <div style={{ height: window.innerHeight }} />
    </>,
  );

  const target = screen.getByText("Observed target");

  await expect.element(target).toHaveAttribute("data-inview", "false");

  window.scrollTo(0, window.innerHeight);

  // Native IntersectionObserver delivery follows the scroll asynchronously.
  await expect.element(target).toHaveAttribute("data-inview", "true");
});

pnpm add -D happy-dom
# or: pnpm add -D jsdom

// vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    globals: true,
    environment: "happy-dom", // "jsdom" works too
    setupFiles: ["./test/setup.ts"],
  },
});

// test/setup.ts
import "react-intersection-observer/test-utils";

// jest.config.js
module.exports = {
  testEnvironment: "jsdom",
  setupFilesAfterEnv: ["react-intersection-observer/test-utils"],
};

import { afterEach, beforeEach, vi } from "vitest";
import {
  resetIntersectionMocking,
  setupIntersectionMocking,
} from "react-intersection-observer/test-utils";

beforeEach(() => setupIntersectionMocking(vi.fn));
afterEach(resetIntersectionMocking);

import { afterEach, beforeEach, jest } from "@jest/globals";
import {
  resetIntersectionMocking,
  setupIntersectionMocking,
} from "react-intersection-observer/test-utils";

beforeEach(() => setupIntersectionMocking(jest.fn));
afterEach(resetIntersectionMocking);

import { render } from "@testing-library/react";
import { expect, test, vi } from "vitest";
import { useOnInView } from "react-intersection-observer";
import { mockAllIsIntersecting } from "react-intersection-observer/test-utils";

function Probe({ onSeen }: { onSeen: (inView: boolean) => void }) {
  const ref = useOnInView((inView) => onSeen(inView));
  return <div ref={ref}>Observed</div>;
}

test("ignores the initial false notification", () => {
  const onSeen = vi.fn();
  render(<Probe onSeen={onSeen} />);

  mockAllIsIntersecting(false);
  expect(onSeen).not.toHaveBeenCalled();

  mockAllIsIntersecting(true);
  expect(onSeen).toHaveBeenCalledWith(true);
});