React Intersection Observer

Common errors

• TypeError: (0 , react_intersection_observer__WEBPACK_IMPORTED_MODULE_2__.useInView) is not a function

  cause This typically occurs when trying to use named ESM exports with a CommonJS `require` call or when a bundler's configuration incorrectly transpiles modules.
  fix Ensure you are using ESM `import` statements: `import { useInView } from 'react-intersection-observer';`. If using TypeScript with CommonJS output, verify your `tsconfig.json` `module` option (e.g., `"ESNext"` or `"Node16"`) and your bundler's settings (e.g., Webpack, Rollup, Vite) support ESM correctly.

• React Hook 'useInView' cannot be called inside a callback. React Hooks must be called in a React function component or a custom React Hook function.

  cause You are attempting to call `useInView` (or any other React Hook) inside a regular JavaScript function, an event handler, or a conditional block, violating the Rules of Hooks.
  fix Move the `useInView` call directly into the body of your React functional component or into another custom hook. Hooks must always be called at the top level of a component or custom hook.

• Element not entering 'inView' state despite being visible in the viewport.

  cause This often happens due to incorrect `threshold` values, `rootMargin` settings, or the `ref` not being correctly attached to the target DOM element.
  fix Double-check your `threshold` (e.g., `threshold: 0` means any part visible, `threshold: 1` means entirely visible) and `rootMargin` (e.g., `rootMargin: '10px 0px'` extends the root bounds). Ensure the `ref` returned by `useInView` is correctly assigned to the DOM element you intend to observe: `<div ref={ref}>...</div>`.

Warnings

• breaking Support for React 15 and 16 has been officially dropped in version 9.14.0. Projects using older React versions will need to remain on a prior major version of `react-intersection-observer` or upgrade their React dependency.
  Fix: Upgrade your project's React and React-DOM dependencies to version 17.0.0 or higher. Alternatively, pin `react-intersection-observer` to a version below 9.14.0, such as `"react-intersection-observer": "^9.13.0"`.
• gotcha The `options` object passed to `useInView` should be stable (e.g., memoized or defined outside the component) to prevent unnecessary re-creation of IntersectionObserver instances, which can lead to performance issues or unexpected behavior.
  Fix: Wrap your `options` object in `React.useMemo` or define it outside the component, especially if it contains complex logic or changes on every render: ```typescript const options = React.useMemo(() => ({ threshold: 0.5, triggerOnce: true }), []); const { ref, inView } = useInView(options); ```
• gotcha The `triggerOnce` option, when combined with merged refs, might skip the initial callback in some edge cases. This was addressed in v10.0.3.
  Fix: Ensure you are on `react-intersection-observer@10.0.3` or newer to benefit from the fix regarding `triggerOnce` and merged refs. If upgrading is not immediately possible, consider alternative logic for `triggerOnce` or simplify ref merging.
• gotcha By design, the first `false` notification from the underlying Intersection Observer is ignored by `useInView` so that handlers only run after a 'real' visibility change. This means your `onChange` callback or `inView` state might not immediately reflect `false` on initial render if the element is not in view.
  Fix: Be aware of this initial behavior. If you need to explicitly handle the initial 'out of view' state, you might need to use a `useEffect` hook with a default `inView` state or an explicit check outside the `useInView` callback.

Install

• npm install react-intersection-observer npm
• yarn add react-intersection-observer yarn
• pnpm add react-intersection-observer pnpm

Imports

• useInView
  wrong:

  const useInView = require('react-intersection-observer').useInView;

  correct:

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

  The primary hook for monitoring viewport intersection. Typically used with object or array destructuring for its return value. Prefer ESM imports.
• InView
  wrong:

  import InView from 'react-intersection-observer';

  correct:

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

  A component-based API alternative to `useInView`, useful for simpler cases or class components. It is a named export, not a default export.
• useOnInView

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

  Introduced in v10.0.0, this hook provides a callback-based API that avoids re-renders for side-effect-only scenarios. It's also a named export.
• IntersectionObserverEntry

  import type { IntersectionObserverEntry } from 'react-intersection-observer';

  When using TypeScript, import `IntersectionObserverEntry` type for precise typing of the entry object received by the hooks/components.

Quickstart

This example demonstrates how to use the `useInView` hook to lazy load an image. The image only renders once it enters the viewport, using `triggerOnce` and a `threshold` of 0.1.

import React from 'react';
import { useInView } from 'react-intersection-observer';

const LazyLoadedImage = ({ src, alt }) => {
  const { ref, inView } = useInView({
    triggerOnce: true, // Only trigger once when it enters the viewport
    threshold: 0.1,    // Trigger when 10% of the element is visible
  });

  return (
    <div ref={ref} style={{ height: '300px', display: 'flex', alignItems: 'center', justifyContent: 'center', background: '#f0f0f0' }}>
      {inView ? (
        <img src={src} alt={alt} style={{ maxWidth: '100%', maxHeight: '100%' }} />
      ) : (
        <p style={{ color: '#888' }}>Loading image...</p>
      )}
    </div>
  );
};

const App = () => {
  return (
    <div>
      <div style={{ height: '100vh', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
        <h1>Scroll Down to See Image</h1>
      </div>
      <LazyLoadedImage src="https://via.placeholder.com/600x300.png?text=Intersection+Observer" alt="Placeholder Image" />
      <div style={{ height: '100vh', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
        <h2>End of Page</h2>
      </div>
    </div>
  );
};

export default App;