README
React Graceful Image
An image component for gracefully dealing with image errors, by providing optional lazy loading, optional placeholder and configurable 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.
Example
1 | 2 | 3 | 4 |
---|---|---|---|
- 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 2 & 4 together.)
Installation
npm install --save react-graceful-image
Basic Usage
import React, { Component } from "react";
import Image from "react-graceful-image";
class YourComponent extends Component {
render() {
return (
<Image
src="path_to_image"
width="300"
height="300"
alt="My awesome image"
/>
);
}
}
Default Behaviour
- Render an SVG placeholder - if environment doesn't support SVG, then avoid rendering the placeholder
- Check if placeholder is within the visible viewport - if so then load the image
- If image loads successfully - display the image by fading it in
- If image fails to load - retry loading the image starting with a 2 second delay and doubling it with every retry (by default retry stops after 8 tries)
Prop Options
Prop | Description | Default | Type |
---|---|---|---|
src |
Image url / path | None | string |
srcSet |
One or more Image urls / paths and their sizes | None | string |
width |
Image width | None | string |
height |
Image height | None | string |
className |
Image class name | None | string |
alt |
Image description | "Broken image placeholder" |
string |
style |
Image styles | None | object |
placeholderColor |
Placeholder's color | "#eee" |
string |
noPlaceholder |
Turn off placeholder rendering | false | bool |
retry |
Retry algorithm's configuration, consisting of count , delay and accumulate |
{count: 8, delay: 2, accumulate: 'multiply'} |
object |
noRetry |
Turn off re-trying | false | bool |
noLazyLoad |
Turn off lazy loading | false | bool |
Retry
You can modify the default retry algorithm by supplying a retry
prop consisting of 3 properties: count
, delay
and accumulate
:
count
specifies the number of times you want to retrydelay
specifies the delay between retries (in seconds)accumulate
specifies how the delay should increase with each retry, possible values:"multiply"
(default),"add"
orfalse
(false can also be represented by simply omitting this property)
Accumulate
accumulate: "multiply"
will multiply delay after each retry by the givendelay
value, i.e. ifdelay: 2
is given then 1st retry will be in 2 seconds, 2nd retry will be in 4 seconds, 3rd retry will be in 8 seconds, 4th retry will be in 16 seconds etc.accumulate: "add"
will increment delay after each retry by the givendelay
value, i.e. ifdelay: 2
is given then 1st retry will be in 2 seconds, 2nd retry will be in 4 seconds, 3rd retry will be in 6 seconds, 4th retry will be in 8 seconds, etc.accumulate: "false"
will keep the delay constant between retries, i.e. ifdelay: 2
is given then retry will run every 2 seconds
Examples
1: 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 10 times, with a fixed 2 second delay between each try.
import React, { Component } from "react";
import Image from "react-graceful-image";
class YourComponent extends Component {
render() {
return (
<Image
src="path_to_image"
width="250"
height="250"
style={{ padding: "20px" }}
alt="My awesome image"
retry={{ count: 10, delay: 2 }}
/>
);
}
}
2: 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).
import React, { Component } from "react";
import Image from "react-graceful-image";
class YourComponent extends Component {
render() {
return (
<Image
src="path_to_image"
className="content-image"
alt="My awesome image"
placeholderColor="#0083FE"
/>
);
}
}
3: 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.
import React, { Component } from "react";
import Image from "react-graceful-image";
class YourComponent extends Component {
render() {
return (
<Image
src="path_to_image"
width="150"
height="150"
style={{ padding: "20px" }}
alt="My awesome image"
retry={{ count: 15, delay: 3, accumulate: "add" }}
/>
);
}
}