Friday, 8 March, 2019 UTC

Summary

imgix for React

A React component that renders images using imgix. It uses the smallest images possible, and renders well on the server.

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

Examples

Basic use case

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.

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}
/>;

NB: Since this library sets fit to crop by default, when just a width or height is set, the image will resize and maintain aspect ratio. When both are set, the image will be cropped to that size, maintaining pixel aspect ratio (i.e. edges are clipped in order to not stretch the photo). If this isn't desired, set fit to be another value (e.g. clip)

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.

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.

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}
/>;

Lazy Loading

If you'd like to lazy load images, we recommend using lazysizes. In order to use react-imgix with lazysizes, you can simply tell it to generate lazysizes-compatible attributes instead of the standard src, srcset, and sizes by changing some configuration settings:

NB: It is recommended to use the attribute change plugin in order to capture changes in the data-* attributes. Without this, changing the props to this library will have no effect on the rendered image.

Low Quality Image Placeholder Technique (LQIP)

If you'd like to use LQIP images, like before, we recommend using lazysizes. In order to use react-imgix with lazysizes, you can simply tell it to generate lazysizes-compatible attributes instead of the standard src, srcset, and sizes by changing some configuration settings, and placing the fallback image src in the htmlAttributes:

NB: If the props of the image are changed after the first load, the low quality image will replace the high quality image. In this case, the src attribute may have to be set by modifying the DOM directly, or the lazysizes API may have to be called manually after the props are changed. In any case, this behaviour is not supported by the library maintainers, so use at your own risk.

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.

Attaching ref to <img />, etc.

A ref passed to react-imgix using <Imgix ref={handleRef}> will attach the ref to the Imgix instance, rather than the DOM element. It is possible to attach a ref to the DOM element that is rendered using htmlAttributes:

<Imgix htmlAttributes={{ ref: handleRef }}>

This works for Source and Picture elements as well.

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.

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.

Props

Shared Props (Imgix, Source)

src :: string, required

Usually in the form: https://[your_domain].imgix.net/[image]. Don't include any parameters.

imgixParams :: object

Imgix params to add to the image src.

For example:

<Imgix imgixParams={{ mask: "ellipse" }} />

sizes :: string

Specified the developer's expected size of the image element when rendered on the page. Similar to width. E.g. 100vw, calc(50vw - 50px), 500px. Highly recommended when not passing width or height. Eric Portis' "Srcset and sizes" article goes into depth on how to use the sizes attribute.

className :: string

className applied to top level component. To set className on the image itself see htmlAttributes.

Picture Props

className :: string

className applied to top level component. To set className on the image itself see htmlAttributes.

onMounted :: func

Called on componentDidMount with the mounted DOM node as an argument.

htmlAttributes :: object

Any other attributes to add to the html node (example: alt, data-*, className).

Background Props

src :: string, required

Usually in the form: https://[your_domain].imgix.net/[image]. Don't include any parameters.

imgixParams :: object

Imgix params to add to the image src. This is also how width and height can be explicitly set. For more information about this, see the "Background" section above.

For example:

<Background imgixParams={{ mask: "ellipse" }} />

className :: string

className applied to top level component. To set className on the image itself see htmlAttributes.

disableLibraryParam :: bool

By default this component adds a parameter to the generated url to help imgix with analytics and support for this library. This can be disabled by setting this prop to true.

htmlAttributes :: object

Any other attributes to add to the html node (example: alt, data-*, className).

Global Configuration

Warnings

This library triggers some warnings under certain situations to try aid developers in upgrading or to fail-fast. These can sometimes be incorrect due to the difficulty in detecting error situations. This is annoying, and so there is a way to turn them off. This is not recommended for beginners, but if you are using custom components or other advanced features, it is likely you will have to turn them off.

Warnings can be turned off with the public config API, PublicConfigAPI, which is exported at the top-level.

Warnings can also be enabled with PublicConfigAPI.enableWarning('<warningName>')

The warnings available are:

warningName

Description

fallbackImage

Triggered when there is no <img> or <Imgix> at the end of the children when using <Picture>. A fallback image is crucial to ensure the image renders correctly when the browser cannot match against the sources provided

sizesAttribute

This library requires a sizes prop to be passed so that the images can render responsively. This should only turned off in very special circumstances.