✨ Introducing react-cool-img: An easy way to optimize images

react-cool-img is a lightweight but powerful React.js image component, which helps you handle image UX (user experience) and performance as a professional guy 🤓. It empowers the standard img tag by many cool features without breaking your original development experience. Ideally, it can be an

img

tag replacement for your React.js project.

Demo Example

Features

🖼 Placeholders for satisfying various image loading states (e.g. loading image > actual image > error image).
🛋 Smart lazy loading with performant and efficient way, using Intersection Observer.
🤖 Built-in auto-retry mechanism. User won't miss out your important information.
🚫 Aborts any current image downloads on component unmount potentially saving bandwidth and browser resources.
🔍 Supports server-side rendering / Javascript is disabled / SEO.
📜 Supports TypeScript type definition.
🦔 Tiny size (~ 2KB gzipped). No external dependencies, aside for the
```
react
```
and
```
react-dom
```
.
🔧 Easy to use.

Usage Example

The default props of the component has been fine-tuned for the purpose of loading optimization. Let's start it as the following example.

import Img from 'react-cool-img';

// Suggest to use low quality or vector images
import loadingImage from './images/loading.gif';
import errorImage from './images/error.svg';

const App = () => (
  <Img
    placeholder={loadingImage}
    src="https://the-image-url"
    error={errorImage}
    alt="React Cool Img"
  />
);

Don't want an image placeholder? No worries, you can use inline styles or CSS for it. The component is fully compatible with the development experience of normal

img

tag.

import Img from 'react-cool-img';

const App = () => (
  <Img
    style={{ backgroundColor: 'grey', width: '480', height: '320' }}
    src="https://the-image-url"
    alt="React Cool Img"
  />
);

The Smart Way to Load Images

Lazy image loading via the Intersection Observer API is good. But could it be greater to download an image only when user want to see it? Or bypass lazy loading for cached images? The answer is yes and these features already be built into react-cool-img by the

debounce

and

cache

props.

By the

debounce

prop, an image can wait to be downloaded while it's in the viewport for a set time. In cases where you have a long list of images that the user might scroll through inadvertently. At this time loading images can cause unnecessary waste of bandwidth and processing time.

import Img from 'react-cool-img';

import defaultImg from './images/default.svg';

const App = () => (
  <Img
    placeholder={defaultImg}
    src="https://the-image-url"
    debounce={1000} // Default is 300 (ms)
    alt="React Cool Img"
  />
);

By the

cache

prop, images you already have cached will abort lazy loading until user visit your app next time. Lazy loading is set up for any remaining images which were not cached. This is helpful for UX, because there's not much extra work to load cached images immediately and is an easy win for making the UI looks more intuitive.

import Img from 'react-cool-img';

import defaultImg from './images/default.svg';

const App = () => (
  <Img
    placeholder={defaultImg}
    src="https://the-image-url"
    cache // Default is true, just for demo
    alt="React Cool Img"
  />
);

JavaScript Availability and SEO

There're two challenges when doing lazy image loading with server-side rendering. One is Javascript availability the other is SEO. Fortunately, we can use <noscript> tag to solve these problems. It will render the actual image as fallback if Javascript is disabled thus user won't see the image which be stuck with the placeholder. Moreover, the

<noscript>

tag ensure the image is indexed by search engine bots even if they cannot fully understand our JavaScript code. Take a look at how magic happens.

const Img = () => {
  // ...

  return (
    <>
      <img
        class="image"
        src="https://the-placeholder-image"
        alt="There's no magic"
      />
      <noscript>
        <img
          class="image"
          src="https://the-actual-image"
          alt="The magic begins in here..."
        />
      </noscript>
    </>
  );
};

Thanks for reading, for more usage details checkout the project's GitHub page: https://github.com/wellyshen/react-cool-img.

You can also install this package is distributed via npm.

$ yarn add react-cool-img
# or
$ npm install --save react-cool-img