Sharing is caring!

React.js <img> tag rendering with multiple fallback & loader support

React Image ???? ???? ????

React Image is an &lt;img&gt; tag replacement for React.js, featuring preloader and multiple image fallback support.

With React Image you can specify multiple images to be used as fallbacks in the event that the browser couldn’t load the previous image. Additionally, you can specify any React element to be used before an image is loaded (i.e. a spinner) and in the event than the specified image(s) could not be loaded.

React Image will cleverly hide “broken” images to prevent showing the browsers default “broken image” placeholder. React Image caches past attempts to load an image so that the same image won’t be attempted to be pulled over the network again, until the next page reload.

This package was formerly known as react-img-multi. Special thanks to @yuanyan for agreeing to relinquish the name!

Getting started

  1. To include the code locally in ES6, CommonJS, or UMD format, install react-image using npm:
npm install react-image --save
  1. To include the code globally from a cdn:
<script src=""></script>


react-image has no external dependencies, aside for the usual react and react-dom.


Include react-image in your component:

// using an ES6 transpiler, like babel
import Img from 'react-image'

// otherwise
let Img = require('react-image')

and set a source for the image:

const myComponent = () =&gt; <img src="">

will generate:

<img src="">

If the image cannot be loaded, &lt;img&gt; will not be rendered, preventing a “broken” image from showing.

Multiple fallback images:

When src is specified as an array, react-image will attempt to load all the images specified in the array, starting at the first and continuing until an image has been successfully loaded.

const myComponent = () =&gt;
  <img src="{[">

If an image has previously been attempted unsuccessfully, react-image will not retry loading it again until the page is reloaded.

Show a “spinner” or other element before the image is loaded:

const myComponent = () =&gt;
  <img src="{[">

If an image was previously loaded successfully (since the last time this page was loaded), the loader will not be shown and the image will be rendered directly instead.

Show a fallback element if non of the images could be loaded:

const myComponent = () =&gt;
  <img src="{[">

Decoding before paint

By default and when supported by the browser, react-image uses img.decode() to decode the image and only render it when it’s fully ready to be painted. While this doesn’t matter much for vector images (such as svg’s) which are rendered immediately, decoding the image before painting prevents the browser from hanging or flashing while the image is decoded. If this behaviour is undesirable, it can be disabled by setting the decode prop to false:

const myComponent = () =&gt;
  <img src="{''}">

Subscribe to the Newsletter

Get our latest news,tutorials,guides,tips & deals delivered to your inbox.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.