React Image Component and Hook

Common errors

• Error: No images were loaded

  cause The `useImage` hook (and implicitly the `Image` component) failed to load any images from the provided `srcList`, and no error boundary is catching the thrown error.
  fix Ensure that at least one URL in `srcList` is valid and accessible, or wrap the component using `useImage` or `Image` in an Error Boundary to catch this exception and display a fallback UI. For example, add `<ErrorBoundary><Image ... /></ErrorBoundary>`.

• TypeError: Object.assign is not a function

  cause The JavaScript environment (browser) does not support `Object.assign`, and no polyfill has been provided. This is common in older browsers like IE.
  fix Include an `Object.assign` polyfill in your application. For example, `import 'es6-object-assign';` or add a script tag for a polyfill from a CDN.

• Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object.

  cause This error typically occurs when trying to default import `Image` (e.g., `import Image from 'react-image'`) instead of using a named import.
  fix Change the import statement to `import { Image } from 'react-image'` to correctly import the named component.

Warnings

• gotcha The package's last publish was over three years ago. While functional, it may not receive frequent updates, bug fixes, or new features, which could be a concern for long-term projects or compatibility with future React versions.
  Fix: Evaluate alternatives if active maintenance and frequent updates are critical for your project.
• breaking For older browser environments that do not natively support `Object.assign`, a polyfill is required. Without it, the application may crash with an error like 'Cannot read properties of undefined (reading 'assign')'.
  Fix: Include an `Object.assign` polyfill (e.g., `es6-object-assign` npm package or Mozilla's polyfill) in your project bundle before `react-image` is loaded.
• gotcha The `react-image` library is not intended for lazy loading images that are off-screen. For performance optimization related to 'lazy loading', it is recommended to use the native HTML `<img>` element with the `loading="lazy"` attribute.
  Fix: Use `<img src="..." loading="lazy" />` directly for lazy loading purposes instead of `react-image`.
• gotcha When using the `useImage` hook, if all provided `srcList` URLs fail to load, the hook will throw an error. Components utilizing `useImage` should be wrapped in a React Error Boundary to gracefully handle these failures and display a custom error state.
  Fix: Implement a React Error Boundary component and wrap any components that use `useImage` within it to catch and display image loading errors.
• gotcha The `useSuspense` prop in `useImage` defaults to `true`, which means the component will suspend rendering until the image is downloaded and decoded. If you are not using React Suspense or want to manage loading states manually, you must explicitly set `useSuspense={false}`.
  Fix: Set `useSuspense={false}` in the `useImage` hook options or the `Image` component props if you do not want to utilize React Suspense for image loading.

Install

• npm install react-image npm
• yarn add react-image yarn
• pnpm add react-image pnpm

Imports

• Image
  wrong:

  import Image from 'react-image'

  correct:

  import { Image } from 'react-image'

  The primary component is a named export, not a default export.
• useImage
  wrong:

  const useImage = require('react-image').useImage

  correct:

  import { useImage } from 'react-image'

  The `useImage` hook is a named export and integrates with React Suspense by default. CommonJS `require` syntax is generally discouraged in modern React/TypeScript projects.
• ImageProps

  import type { ImageProps } from 'react-image'

  Type import for the component's props, useful for TypeScript projects.

Quickstart

This example showcases the `Image` component with a `Suspense` boundary, providing a custom loader and a fallback component if all specified images fail to load. It uses `srcList` for multiple fallback image sources.

import React, { Suspense } from 'react';
import { Image } from 'react-image';

const PlaceholderComponent: React.FC = () => (
  <div style={{ background: '#f0f0f0', height: '200px', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
    Loading Image...
  </div>
);

const ErrorFallbackComponent: React.FC = () => (
  <div style={{ background: '#ffcccc', color: '#cc0000', height: '200px', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
    Failed to load image.
  </div>
);

const App: React.FC = () => {
  const imageUrls = [
    'https://picsum.photos/800/600?random=1', // Primary image
    'https://picsum.photos/600/400?random=2', // Fallback image 1
    'https://upload.wikimedia.org/wikipedia/commons/thumb/1/11/Test-Logo.svg/783px-Test-Logo.svg.png' // Fallback image 2
  ];

  return (
    <div style={{ fontFamily: 'sans-serif', padding: '20px' }}>
      <h1>React Image Example</h1>
      <p>This demonstrates loading an image with a custom placeholder and multiple fallbacks.</p>
      <div style={{ maxWidth: '800px', margin: '20px auto', border: '1px solid #ddd' }}>
        <Suspense fallback={<PlaceholderComponent />}>
          <Image
            srcList={imageUrls}
            loader={<PlaceholderComponent />}
            alt="Random unsplash image"
            style={{ width: '100%', height: 'auto', display: 'block' }}
            errorFallback={<ErrorFallbackComponent />}
          />
        </Suspense>
      </div>
      <p>Note: The first valid URL from `srcList` will be used. If all fail, `errorFallback` is shown.</p>
    </div>
  );
};

export default App;