An image component for gracefully dealing with image errors, by providing optional lazy loading, an optional placeholder and retries on failure. Particularly useful in situations where your application might be used in poor signal areas such as when travelling on a train, a bus or a car.
Visual Example
- Default browser behaviour when image fails due to bad signal
- With react-graceful-image placeholder
- With react-graceful-image disabled placeholder
- With react-graceful-image retries — if the image fails to load, the package will gracefully re-attempt loading the image again
(note: these are not mutually exclusive, for example the default behaviour makes use of both a placeholder and retries together.)
Implementation
Placeholder
- Implemented as an SVG embedded into a Data URI — this means that you don’t have to fire an extra HTTP request in order to download the placeholder, it is embedded right into the component
- The component also provides a way to customize the placeholder by changing it’s color via the
placeholderColorprop — as well as via a regularstylesorclassNameprops ( note that styles passed this way are also passed to the actual image.) - It also gives you the option of disabling the placeholder, in which case the image will not render at all until it is loaded — since the image will not get rendered until it successully loads this also means that incase the image fails it will not take its intended space on the page and you will not get a broken image icon
Retry
- Implemented using
setTimeoutwhich plays around with the delay and the desired number of retries in an attempt to gracefully re-load the image - By default the delay in between retries doubles on every retry, this can however be modified via the
retry.accumulateprop which accepts one of the following values ‘multiply’, ‘add’, ‘noop’ and updates the retry algorithm accordingly (note you can also change the delay time and retry count)
Usage Example
The below code snippet will display a blue SVG placeholder, if it is within the visible viewport then it will load the actual given image and fade it in once it is done loading. If loading the image fails, then it will retry loading the image again for a maximum of 8 times, with initial delay of 2 seconds, which will then increase to 4 seconds, then to 8 seconds, then to 16 seconds, and so on (default retry configuration). It will also apply whatever styles are defined inside of the ‘content-image’ className to the placeholder (and the image once the image loads).
import React, { Component } from 'react'import Image from 'react-graceful-image'
class YourComponent extends Component {render() {return (<Imagesrc="path_to_image"className="content-image"alt="My awesome image"placeholderColor="#0083FE"/>);}}
The below code snippet will display a light grey (default) SVG placeholder, if it is within the visible viewport then it will load the actual given image and fade it in once it is done loading. If loading the image fails, then it will retry loading the image again for a maximum of 15 times, with initial delay of 3 seconds which will then increase to 6 seconds, then to 9 seconds, then to 12 seconds, and so on. It will apply 20px of padding to the placeholder (and the image once the image loads).
import React, { Component } from 'react'import Image from 'react-graceful-image'
class YourComponent extends Component {render() {return (<Imagesrc="path_to_image"width="150"height="150"style={{padding: '20px'}}alt="My awesome image"retry={{count: 15, delay: 3, accumulate: 'add'}}/>);}}
Thanks for reading, for more usage details checkout the projects github page: https://github.com/linasmnew/react-graceful-image. You can also install it via npm using: npm install --save react-graceful-image