react-imgix
provides custom components for integrating imgix into React sites and generating images server-side.
- Overview / Resources
- Installation
- Usage
- Upgrade Guides
- 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 withsrcset
andsizes
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&crop=faces&ixlib=react-7.2.0"
sizes="100vw"
srcset="
https://assets.imgix.net/examples/pione.jpg?auto=format&crop=faces&ixlib=react-7.2.0&w=100 100w,
https://assets.imgix.net/examples/pione.jpg?auto=format&crop=faces&ixlib=react-7.2.0&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