React Lazy Load Component

Common errors

• TypeError: Cannot read properties of undefined (reading 'IntersectionObserver')

  cause The browser or environment where the component is rendered does not support the Intersection Observer API, which v4+ of `react-lazy-load` relies on.
  fix Ensure you are running in a modern browser environment or provide a polyfill for Intersection Observer if supporting older browsers.

• LazyLoad component's content is visible immediately, even if off-screen.

  cause This usually happens when `height` or `width` props are not set, preventing the Intersection Observer from accurately determining the element's dimensions and visibility.
  fix Always set the `height` and/or `width` props on the `<LazyLoad>` component, especially when using `threshold`, to give the browser proper dimensions for observation.

• Warning: Prop `threshold` was not expected. Did you mean `offset`?

  cause This warning indicates you are likely using a version between 3.0.0 and 4.0.0, where the `threshold` prop was deprecated in favor of `offset`.
  fix Upgrade to v4.0.0 or later to use the `threshold` prop with Intersection Observer semantics, or switch to using the `offset` prop for earlier v3 versions.

• Error: Invalid hook call. Hooks can only be called inside of the body of a function component.

  cause This generic React error can occur if `react` and `react-dom` peer dependencies are not met or if multiple versions of React are being loaded, causing context issues for the component.
  fix Verify that your `react` and `react-dom` versions satisfy the `react-lazy-load` peer dependency (`^17.0.0 || ^18.0.0` for v4+) and resolve any duplicate React installations in your `node_modules`.

Warnings

• breaking With the release of v4.0.0, the `debounce` and `throttle` options have been entirely removed as they are no longer necessary due to the adoption of the Intersection Observer API.
  Fix: Remove `debounce` and `throttle` props from your `LazyLoad` components. The Intersection Observer API inherently handles performance efficiently.
• breaking In v4.0.0, the `offset` prop's behavior changed significantly. It now accepts a number (for uniform offset) or a CSS-like string (e.g., '10px 20px 0 0' for top, right, bottom, left offsets), and individual `offset*` props (e.g., `offsetTop`) were removed.
  Fix: Consolidate individual offset props into the single `offset` prop using a number or CSS margin-like string. For example, change `offsetTop={100}` to `offset={100}` or `offset={'100px 0 0 0'}`.
• breaking Version 3.0.0 introduced breaking changes to the default CSS class names used by the component. Old classes like `.lazy-load` and `.lazy-load-visible` were renamed.
  Fix: Update your CSS selectors from `.lazy-load` to `.LazyLoad` and from `.lazy-load-visible` to `.is-visible`.
• gotcha The `threshold` prop was deprecated in v3.0.0 in favor of `offset`. However, a new `threshold` prop was *re-introduced* in v4.0.0 with a different meaning, tied to the Intersection Observer API (a number between 0 and 1 indicating percentage of visibility). Do not confuse the old deprecated `threshold` with the new v4 `threshold`.
  Fix: If migrating from v3, replace the old `threshold` usage with `offset`. If using v4+, `threshold` should be a number between 0 and 1 and typically requires `width` and `height` props for accurate calculation by the browser.
• breaking Beginning with v4.0.0, `react-lazy-load` requires React 17 or later as a peer dependency. Previous versions had different React peer dependency requirements.
  Fix: Ensure your project's React and React DOM versions are `^17.0.0 || ^18.0.0` to satisfy peer dependency requirements.

Install

• npm install react-lazy-load npm
• yarn add react-lazy-load yarn
• pnpm add react-lazy-load pnpm

Imports

• LazyLoad
  wrong:

  import { LazyLoad } from 'react-lazy-load'; // Not a named export, it's the default.

  correct:

  import LazyLoad from 'react-lazy-load';

  The primary component is a default export.
• LazyLoadProps

  import type { LazyLoadProps } from 'react-lazy-load';

  Type import for component props, available since v4 with TypeScript support.
• require
  wrong:

  import LazyLoad from 'react-lazy-load';

  correct:

  const LazyLoad = require('react-lazy-load');

  CommonJS `require` syntax for older Node.js environments or projects not using ESM.

Quickstart

This quickstart demonstrates basic usage of the LazyLoad component, showing how to wrap an image, specify height, use `offset` to load content before it's fully visible, and `threshold` for a specific visibility percentage (v4+), including a callback for content visibility.

import React from 'react';
import LazyLoad from 'react-lazy-load';

const MyImageGallery = () => (
  <div>
    <h1>My Lazy Loaded Gallery</h1>
    <p>Scroll down to see images load as they enter the viewport.</p>
    <div style={{ height: '800px', background: '#eee' }}>
      {/* Placeholder to create scroll space */}
      Content above the fold.
    </div>
    <LazyLoad height={300} offset={200} onContentVisible={() => console.log('Image 1 loaded!')}>
      <img 
        src='https://via.placeholder.com/600x300/FF5733/FFFFFF?text=Lazy+Image+1'
        alt='Placeholder Image 1'
        style={{ display: 'block', maxWidth: '100%' }}
      />
    </LazyLoad>
    <div style={{ height: '500px', background: '#ddd' }}>
      {/* More placeholder content */}
      More content to scroll past.
    </div>
    <LazyLoad height={400} threshold={0.75} onContentVisible={() => console.log('Image 2 loaded!')}>
      <img 
        src='https://via.placeholder.com/800x400/33FF57/000000?text=Lazy+Image+2'
        alt='Placeholder Image 2'
        style={{ display: 'block', maxWidth: '100%' }}
      />
    </LazyLoad>
    <div style={{ height: '1000px', background: '#ccc' }}>
      {/* Final placeholder content */}
      Even more content at the bottom.
    </div>
  </div>
);

export default MyImageGallery;