Name: react-imgix
Brand: react-imgix
SKU: //imgix/react-imgix
Rating: 2.4175 (267 reviews)

imgix/ react-imgix

(v9.0.3) 4 months ago

React

JavaScript

src

reactjs

View on GitHub

Need help with react-imgix?

Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

imgix

267 Stars

53 Forks

Other

706 Commits

19 Opened issues

Description

React component to display imgix images

Services available

Need anything else?

Contributors list

Readme

react-imgix

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

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

import Imgix from "react-imgix";

;

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

;

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

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

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

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

and

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.

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 base URL may also contain query parameters. These will be overridden by any parameters passed in with the second parameter.

This feature can be used to create your own custom

img

elements, or for use with other image components, such as React-bootstrap's Image component.

The

ixlib

parameter may be disabled by:

buildURL(, , { disableLibraryParam: true })

Passing Custom HTML Attributes

This library allows the developer to pass any attribute they like to the underlying DOM element with

htmlAttributes

For example, if the the developer would like to attach a custom

onLoad

callback to an

img

component:

 handleImgOnLoad,
  }}
/>

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:

The same configuration is available for

components

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.

Attaching Ref to DOM Elements

ref

passed to react-imgix using

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

This works for Source and Picture elements as well.

Props

Shared Props (Imgix, Source)

These props are shared among Imgix and Source Components

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:

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

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

height :: number

Force images to be a certain height.

width :: number

Force images to be a certain width.

disableSrcSet :: bool, default = false

Disable generation of variable width src sets to enable responsiveness.

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

onMounted :: func

Called on

componentDidMount

with the mounted DOM node as an argument.

attributeConfig :: object

Allows the src, srcset, and sizes attributes to be remapped to different HTML attributes. For example:

  attributeConfig={{
    src: 'data-src',
    srcSet: 'data-srcset',
    sizes: 'data-sizes'
  }}

This re-maps src to

data-src

, srcSet to

data-srcset

, etc.

disableQualityByDPR :: bool, default = false

Disable generation of variable

parameters when rendering a fixed-size image.

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:

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.

// in init script/application startup
import { PublicConfigAPI } from "react-imgix";

PublicConfigAPI.disableWarning('');
//... rest of app startup
React.render(...);

Warnings can also be enabled with

PublicConfigAPI.enableWarning('')

The warnings available are:

warningName

| Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | fallbackImage | Triggered when there is no

at the end of the children when using

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

Upgrade Guides

8.x to 9.0

This release brings the react-imgix API more in-line with that of imgix's rendering service.

The largest change users will notice is that this project's component will no longer generate a default

fit=crop

parameter. The original intention behind this was that generated images would maintain aspect ratio when at least one of the dimensions were specified. However, the default imgix API behavior sets

fit=clip

, which is now reflected in this project. Although this may not cause breaking changes for all users, it can result in unusual rendered image behavior in some cases. As such, we would rather err on the side of caution and provide users the ability to opt in to these changes via a major release.

If you are currently relying on the default generation of

fit=crop

when rendering images, you will now have to manually specify it when invoking the component:

The other major change relates to how the component determines an image's aspect ratio. Instead of appending a calculated height

h=

value based on specified dimensions, the URL string will now be built using the imgix aspect ratio parameter

ar=

. Luckily, the interface for specifying an aspect ratio is no different from before. However, users will have to pass in the

fit=crop

parameter in order for it to take effect:

7.x to 8.0

This is a very large update to this library with a lot of breaking changes. We apologise for any issues this may cause, and we have tried to reduce the number of breaking changes. We have also worked to batch up all these changes into one release to reduce its impacts. We do not plan on making breaking changes for a while after this, and will be focussed on adding features.

The largest change in this major version bump is the move to width-based

srcSet

and

sizes

for responsiveness. This has a host of benefits, including better server rendering, better responsiveness, less potential for bugs, and performance improvements. This does mean that the old fitting-to-container-size behaviour has been removed. If this is necessary, an example of how this can be achieved can be found here

To upgrade to version 8, the following changes should be made.

A
```
sizes
```
prop should be added to all usages of Imgix. If
```
sizes
```
is new to you (or even if it's not), Eric's
seminal article on
```
srcset
```
and
```
sizes
```
is highly recommended.
Change all usages of
```
type='picture'
```
to
and
```
type='source'
```
to
```
// this...

  
  


// becomes...

  
  
```
See Picture support for more information.
Remove all usage of
```
type='bg'
```
as it is no longer supported. It was decided that it was too hard to implement this feature consistently. If you would still like to use this feature, please give this issue a thumbs up: https://github.com/imgix/react-imgix/issues/160 If we get enough requests for this, we will re-implement it.
Remove props
```
aggressiveLoad
```
,
```
component
```
,
```
fluid
```
,
```
precision
```
as they are no longer used.
Change all usages of
```
defaultHeight
```
and
```
defaultWidth
```
to
```
width
```
and
```
height
```
props.

Rename

generateSrcSet

disableSrcSet

and invert the value passed down as the prop's value. i.e.

generateSrcSet={false}

becomes

disableSrcSet={true}

or simply

disableSrcSet

If support is needed for a browser which does not support the new usage of srcSet (such as IE 11), we recommended adding a polyfill, such as the great Picturefill.

Browser Support

By default, browsers that don't support
```
srcset
```
,
```
sizes
```
, or
```
picture
```
will gracefully fall back to the default
```
img
```
```
src
```
when appropriate. If you want to provide a fully-responsive experience for these browsers, react-imgix works great alongside Picturefill!
We support the latest version of Google Chrome (which automatically updates whenever it detects that a new version of the browser is available). We also support the current and previous major releases of desktop Firefox, Internet Explorer, and Safari on a rolling basis. Mobile support is tested on the most recent minor version of the current and previous major release for the default browser on iOS and Android (e.g., iOS 9.2 and 8.4). Each time a new version is released, we begin supporting that version and stop supporting the third most recent version.

This browser support is made possible by the great support from BrowserStack.

Contributors

Thanks goes to these wonderful people (emoji key):

_{Frederick Fogerty} 💻 📖 🚧 💬	_sherwinski 💻 📖 🚧 💬	_{Jason Eberle} 💻 📖 🚧 💬	_{Paul Straw} 🚧	_{Kelly Sutton} 🚧	_{Richard Bliss} 💻 ⚠️	_{Eric Koslow} 💻 📖
_{Baldur Helgason} 💻	_{jonathan schatz} 💻	_Theo 💻	_{Tanner Stirrat} 💻 🐛	_{Nicholas Suski} 💻	_voiceup 💻	_{Craig Kochis} 💻
_{Dennis Schaaf} 💻	_{Andy Kent} 💻	_{Gabby Losch} 💻	_{Stephen Cook} 💻 🐛	_{Eugene Nagorny} 📖	_{Samuel Giles} 📖	_{Espen Hovlandsdal} 📖
_{Daniel Farrell} 📖	_{Luiz Fernando da Silva Cieslak} 📖	_{Nick Gottlieb} 📖	_{Pierre Grimaud} 📖	_{Luis H. Ball Jr.} 💻

This project follows the all-contributors specification. Contributions of any kind welcome, but please review the contribution guidelines before getting started!

About the developer

Description

Services available

Need anything else?

Contributors list

Overview / Resources

Installation

Usage

Examples

Basic Use Case

Server-Side Rendering

Flexible Image Rendering

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

Background Mode

Blog Title

Blog Title

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)

src :: string, required

imgixParams :: object

sizes :: string

className :: string

height :: number

width :: number

disableSrcSet :: bool, default = false

disableLibraryParam :: bool

htmlAttributes :: object

onMounted :: func

attributeConfig :: object

disableQualityByDPR :: bool, default = false

Picture Props

className :: string

onMounted :: func

htmlAttributes :: object

Background Props

src :: string, required

imgixParams :: object

className :: string

disableLibraryParam :: bool

htmlAttributes :: object

Global Configuration

Warnings

Upgrade Guides

8.x to 9.0

7.x to 8.0

Browser Support

Contributors

Meta