react-image

library4.1.0jsnpmunverified

React Image is a library providing a robust `<img>` tag replacement and a `useImage` hook for React applications. It focuses on enhancing image loading by supporting multiple image sources for fallback, displaying custom preloader components while images are loading, and gracefully handling image loading errors. The current stable version is 4.1.0, but the package was last published over three years ago, suggesting a maintenance rather than active development cadence. A key differentiator is its internal `useImage` hook, which leverages React Suspense by default for declarative image loading states. It explicitly advises against using it for lazy loading, recommending native browser `loading="lazy"` for that purpose. It allows developers to specify any React element as a loading indicator or an error fallback, providing a more polished user experience than default browser behaviors.

web-framework

npm install react-image

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-IMAGE

react-image

web-frameworkjavascriptv4.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Image

✓ import { Image } from 'react-image'

✗ import Image from 'react-image'

The primary component is a named export, not a default export.

useImage

✓ import { useImage } from 'react-image'

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

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.

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;

Debug

Known issues

gotchaThe 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.

affects: >=4.1.0

breakingFor 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.

affects: >=1.0.0

gotchaThe `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`.

affects: >=1.0.0

gotchaWhen 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.

affects: >=4.0.0

gotchaThe `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.

affects: >=4.0.0

Errors

Common errors & fixes

Error: No images were loaded

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

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.

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.

Upgrade

Version history

4.1.0latest on npm

Audit

Dependencies

@babel/runtimerequiredRuntime helper functions for Babel-transformed code.

reactrequiredCore React library; supports hooks since >=16.8.

react-domrequiredReactDOM for browser rendering; supports hooks since >=16.8.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/mbrevda/react-image ↗

packagehttps://www.npmjs.com/package/react-image ↗