JS.coach

react-imgix provides custom components for integrating imgix into React sites and generating images server-side.

• Overview / Resources
• Installation
• Usage
  • Examples
    • Basic Use Case
    • Server-Side Rendering
    • Flexible Image Rendering
    • Fixed Image Rendering (i.e. non-flexible)
    • Background Mode
    • Picture Support
  • Advanced Examples
    • General Advanced Usage
    • Passing Custom HTML Attributes
    • Lazy Loading
    • Low Quality Image Placeholder Technique (LQIP)
    • Attaching Ref to DOM Elements
  • Props
    • Shared Props (Imgix, Source)
    • Picture Props
    • Background Props
  • Global Configuration
    • Warnings
• Upgrade Guides
  • 8.x to 9.0
  • 7.x to 8.0
• Browser Support
• Contributors
• Meta

Overview / Resources

Before you get started with react-imgix, it's highly recommended that you read Eric Portis' seminal article on srcset and sizes. This article explains the history of responsive images in responsive design, why they're necessary, and how all these technologies work together to save bandwidth and provide a better experience for users. The primary goal of react-imgix is to make these tools easier for developers to implement, so having an understanding of how they work will significantly improve your react-imgix experience.

Below are some other articles that help explain responsive imagery, and how it can work alongside imgix:

• Using imgix with <picture>. Discusses the differences between art direction and resolution switching, and provides examples of how to accomplish art direction with imgix.
• Responsive Images with srcset and imgix. A look into how imgix can work with srcset and sizes to serve the right image.

Installation

• NPM: npm install react-imgix
• Yarn: yarn add react-imgix

This module exports two transpiled versions. If a ES6-module-aware bundler is being used to consume this module, it will pick up an ES6 module version and can perform tree-shaking. If you are not using ES6 modules, you don't have to do anything

Usage

import Imgix from "react-imgix";
// in react component
<Imgix src={string} />;

Examples

Basic Use Case

For simply using as you would use an <img>, react-imgix can be used as follows:

import Imgix from "react-imgix";

<Imgix src="https://assets.imgix.net/examples/pione.jpg" sizes="100vw" />;

Please note: 100vw is an appropriate sizes value for a full-bleed image. If your image is not full-bleed, you should use a different value for sizes. Eric Portis' "Srcset and sizes" article goes into depth on how to use the sizes attribute.

This will generate HTML similar to the following:

<img
  src="https://assets.imgix.net/examples/pione.jpg?auto=format&amp;crop=faces&amp;ixlib=react-7.2.0"
  sizes="100vw"
  srcset="
    https://assets.imgix.net/examples/pione.jpg?auto=format&amp;crop=faces&amp;ixlib=react-7.2.0&amp;w=100 100w,
    https://assets.imgix.net/examples/pione.jpg?auto=format&amp;crop=faces&amp;ixlib=react-7.2.0&amp;w=200 200w,
    ...
  "
/>

Since imgix can generate as many derivative resolutions as needed, react-imgix calculates them programmatically, using the dimensions you specify. All of this information has been placed into the srcset and sizes attributes.

Width and height known: If the width and height are known beforehand, it is recommended that they are set explicitly:

import Imgix from "react-imgix";

<Imgix
  src="https://assets.imgix.net/examples/pione.jpg"
  width={100} // This sets what resolution the component should load from the CDN and the size of the resulting image
  height={200}
/>;

Server-Side Rendering

React-imgix also works well on the server. Since react-imgix uses srcset and sizes, it allows the browser to render the correctly sized image immediately after the page has loaded.

import Imgix from "react-imgix";

<Imgix src="https://assets.imgix.net/examples/pione.jpg" sizes="100vw" />;

If the width and height are known beforehand, it is recommended that they are set explicitly:

import Imgix from "react-imgix";

<Imgix
  src="https://assets.imgix.net/examples/pione.jpg"
  width={100} // This sets what resolution the component should load from the CDN and the size of the resulting image
  height={200}
/>;

Flexible Image Rendering

This component acts dynamically by default. The component will leverage srcset and sizes to render the right size image for its container. This is an example of this responsive behaviour.

sizes should be set properly for this to work well, and some styling should be used to set the size of the component rendered. Without sizes and correct styling the image might render at full-size.

./styles.css

.App {
  display: flex;
}

.App > img {
  margin: 10px auto;
  width: 10vw;
  height: 200px;
}

./app.js

import "./styles.css";

<div className="App">
  <Imgix
    src="https://assets.imgix.net/examples/pione.jpg"
    sizes="calc(10% - 10px)"
  />
</div>;

Aspect Ratio: A developer can pass a desired aspect ratio, which will be used when generating srcsets to resize and crop your image as specified. For the ar parameter to take effect, ensure that the fit parameter is set to crop.

<div className="App">
  <Imgix
    src="https://assets.imgix.net/examples/pione.jpg"
    sizes="calc(10% - 10px)"
    imgixParams={{ ar: "16:9" }}
  />
</div>

The aspect ratio is specified in the format width:height. Either dimension can be an integer or a float. All of the following are valid: 16:9, 5:1, 1.92:1, 1:1.67.

Fixed Image Rendering (i.e. non-flexible)

If the fluid, dynamic nature explained above is not desired, the width and height can be set explicitly.

import Imgix from "react-imgix";

<Imgix
  src="https://assets.imgix.net/examples/pione.jpg"
  width={100} // This sets what resolution the component should load from the CDN and the size of the resulting image
  height={200}
/>;

Fixed image rendering will automatically append a variable q parameter mapped to each dpr parameter when generating a srcset. This technique is commonly used to compensate for the increased filesize of high-DPR images. Since high-DPR images are displayed at a higher pixel density on devices, image quality can be lowered to reduce overall filesize without sacrificing perceived visual quality. For more information and examples of this technique in action, see this blog post. This behavior will respect any overriding q value passed in via imgixParams and can be disabled altogether with the boolean property disableQualityByDPR.

<Imgix src="https://domain.imgix.net/image.jpg" width={100} disableQualityByDPR />

will generate the following srcset:

https://domain.imgix.net/image.jpg?q=75&w=100&dpr=1 1x,
https://domain.imgix.net/image.jpg?q=50&w=100&dpr=2 2x,
https://domain.imgix.net/image.jpg?q=35&w=100&dpr=3 3x,
https://domain.imgix.net/image.jpg?q=23&w=100&dpr=4 4x,
https://domain.imgix.net/image.jpg?q=20&w=100&dpr=5 5x

Background Mode

Images can be rendered as a background behind children by using <Background />. The component will measure the natural size of the container as determined by the CSS on the page, and will render an optimal image for those dimensions.

Example:

// In CSS
.blog-title {
  width: 100vw;
  height: calc(100vw - 100px);
}

// In Component (React)
import { Background } from 'react-imgix'

<Background src="https://.../image.png" className="blog-title">
  <h2>Blog Title</h2>
</Background>

This component shares a lot of props that are used in the main component, such as imgixParams, and htmlAttributes.

As the component has to measure the element in the DOM, it will mount it first and then re-render with an image as the background image. Thus, this technique doesn't work very well with server rendering. If you'd like for this to work well with server rendering, you'll have to set a width and height manually.

Set width and height:

Setting the width and/or height explicitly is recommended if you already know these beforehand. This will save the component from having to do two render passes, and it will render a background image immediately.

This is accomplished by passing w and h as props to imgixParams.

<Background
  src="https://.../image.png"
  imgixParams={{ w: 1920, h: 500 }}
  className="blog-title"
>
  <h2>Blog Title</h2>
</Background>

Picture Support

Using the picture element you can create responsive images:

import Imgix, { Picture, Source } from "react-imgix";

<Picture>
  <Source
    src={src}
    width={400}
    htmlAttributes={{ media: "(min-width: 768px)" }}
  />
  <Source
    src={src}
    width={200}
    htmlAttributes={{ media: "(min-width: 320px)" }}
  />
  <Imgix src={src} imgixParams={{ w: 100 }} />
</Picture>;

In order to reduce the duplication in props, JSX supports object spread for props:

import Imgix, { Picture, Source } from 'react-imgix'

const commonProps = {
  src: 'https://...',
  imgixParams: {
    fit: 'crop',
    crop: 'faces'
  }
}

<Picture>
  <Source
    {...commonProps}
    width={400}
    htmlAttributes={{ media: "(min-width: 768px)" }}
  />
  <Source
    {...commonProps}
    width={200}
    htmlAttributes={{ media: "(min-width: 320px)" }}
  />
  <Imgix src={src} width={100} />
</Picture>

A warning is displayed when no fallback image is passed. This warning can be disabled in special circumstances. To disable this warning, look in the warnings section.

Advanced Examples

General Advanced Usage

Although imgix is open to feature suggestions, we might not accept the feature if it is a very specific use case. The features below are examples of what we consider general advanced use cases. Our target here is to support 95% of all the usages of normal img, picture, and source elements.

If your desired feature falls outside this percentage, do not worry! You will probably still be able to achieve your feature with react-imgix's more powerful API: buildURL.

This library exposes a pure function, buildURL, for generating full imgix URLs given a base URL and some parameters.

import { buildURL } from "react-imgix";

buildURL("http://yourdomain.imgix.net/image.png", { w: 450, h: 100 }); // => http://yourdomain.imgix.net/image.png?auto=format&w=450&h=100&ixlib=react-x.x.x

The