react-imgix

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
    • ImgixProvider Component
  • 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 ``. 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
;

Examples

Basic Use Case

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

import Imgix from "react-imgix";

;

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:

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 and fixed: If the width and height are known beforehand, and a fixed-size image is wanted, it is recommended that they are set explicitly:

import Imgix from "react-imgix";

;

When width and height are specified, `` will give the image a srcset with resolution descriptors.

Width and height known but fluid: If the image's intrinsic width and height are known but a fluid size image is wanted, width and height should still be set to avoid layout shift, but they must be set via htmlAttributes so as not to hint to `` to produce resolution descriptors in the srcset.

import Imgix from "react-imgix";

 element
    width: 200,
    height: 100,
  }}
/>;

In this example, `` will produce a srcset with width descriptors.

Server-Side Rendering

Note This library does not run in Server Components but instead adds the "use client" directive to components. This means they are able to be used alongside Server Components (for example, as children), but they still require client-side JavaScript. Client Components are still SSRed.

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 they are known, pass width and height attributes via htmlAttributes to help combat layout shift.

import Imgix from "react-imgix";

;

If the width and height are known beforehand, and a fixed-size image is wanted, set width and height and do not set sizes:

import Imgix from "react-imgix";

;

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";

;

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.

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";

;

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.

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 ``. 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'

  
Blog Title

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.

  
Blog Title

Picture Support

Using the picture element you can create responsive images:

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

  
  
  

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",
  },
};

  
  
  

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.

ImgixProvider Component

The Higher Order Component (HOC), makes its [props](#props) available to any nested component in your React application.

For example, by rendering at the top level of your application with `imgixParams` defined, all your components will have access to the same imgixParams.

import React from "react";
import Imgix, { ImgixProvider } from "react-imgix";
import HomePage from "./components/HomePage";

function App() {
  return (
    

          

        
      
    
  );
}

export default App;

So that the generated HTML looks something like

You can take advantage of this behavior to use partial URLs with the component. By defining the [`domain`](#domain--string-optional) prop on the Provider, it can be made accessible to all nested components.

// inside App.jsx
{
  /*... */
}

  

  

;
{
  /*... */
}

Both the `` components above will access to the domain prop from the provider and have their relative src paths resolve to the same domain. So that the generated HTML looks something like:

The props that makes accessible can also be overridden by components. Any prop defined on the `` component will override the value set by the Provider.

// inside App.jsx
{
  /*... */
}

  

  

;
{
  /*... */
}

So that the generated HTML looks something like this

To remove a shared prop from an `` component, the same prop can be set to undefined on the component itself.

// inside App.jsx
{
  /*... */
}

  

  

;
{
  /*... */
}

So that the generated HTML looks something like this:

You can nest ImgixProvider components to ensure that different consumers have different props.

For example to give Imgix components different props from Picture components, you can nest an ImgixProvider inside of another one.

The nested Provider will change the Context for the Picture component, essentially removing their access to the shared props provided by the root ImgixProvider.

import React from 'react'
import Imgix, { ImgixProvider, Picture, Source } from "react-imgix";
export default function simpleImage() {
  return (
    

  )
}

Advanced Examples

General Advanced Usage

Although