React image transformations

Overview

After you or your users have uploaded image assets to Cloudinary, you can deliver them via dynamic URLs. You can include instructions in your dynamic URLs that tell Cloudinary to manipulate your assets using a set of transformation parameters. All manipulations are performed automatically in the cloud and your transformed assets are automatically optimized before they are routed through a fast CDN to the end user for optimal user experience.

For example, you can resize and crop, add overlay images, blur or pixelate faces, apply a large variety of special effects and filters, and apply settings to optimize your images and to deliver them responsively.

Cloudinary's React library simplifies the generation of transformation URLs for easy embedding of assets in your React application.

See also: React video manipulation

Deliver and transform images

You deliver your images using the Image component. The output is a complete HTML <img> tag whose src is the relevant transformation URL.

Copy to clipboard
   <Image publicId="mypic" />

is compiled by React to:

Copy to clipboard
<img src="https://res.cloudinary.com/{cloud_name}/image/upload/mypic">

You can add optional Transformation elements that will be used as chained transformations (each transformation is applied to the result of the previous transformation).

For example, the following code crops the image to 150x150, rounds the corners, applies a sepia effect, adds text to the top center of the resized image, and then rotates the entire result by 20 degrees.

Copy to clipboard
<Image publicId="mypic">
  <Transformation height="150" width="150" crop="fill" effect="sepia" radius="20" />
  <Transformation overlay="text:arial_60:This is my picture" gravity="north" y="20" />
  <Transformation angle="20" />
</Image>

You can also add other, non-transformation parameters to the Image component such as the asset version, configuration parameters and HTML5 image tag attributes.

For example:

Copy to clipboard
<Image publicId="docs/casual" version="1573726751" cloud_name="demo" secure="true" alt="Casual Jacket" height="500" width="500" crop="fill" />
</Image>

is compiled by React to:

Copy to clipboard
<img src="https://res.cloudinary.com/demo/image/upload/c_fill,h_500,w_500/v1573726751/docs/casual" alt="Casual Jacket">

Referencing the HTML image element

If you would like to reference the underlying image HTML element created by the Image component, you can pass an innerRef parameter to the Image component. This will then allow you to access the image elements attributes, for example, src.

Copy to clipboard
let myRef = React.createRef();

// and then in render()
<Image
  innerRef={myRef}
  publicId='sample'
/>

// to access the image URL after the component is mounted

const imageElement = myRef.current;    // Get the img element
const url = imageElement.src;

Advanced image components

The SDK supports some advanced image components to improve your user's experience:

  • Lazy Loading to delay loading images if they are not yet visible on the screen.
  • Image placeholders to display a lightweight version of an image while the target image is downloading.
  • Image accessibility to make your images more accessible to your users with visual disabilities.

Lazy loading

Lazy loading tells the browser not to download images that are not yet visible to the user on his screen, and wait until the user scrolls to that image. This feature can potentially save bandwidth for images that are not actually viewed, and decrease the time needed to load a page.

To enable the lazy loading feature for a particular image, add the loading attribute to the <Image> component with a value of "lazy".

For example:

Copy to clipboard
<Image 
  public-id="sample" 
  loading="lazy"
  width="400"
  height="300">
</Image>

Note
To avoid your page content 'jumping' as the elements dynamically adjust to add downloaded images, make sure to add the height and width attributes to the Image component, as in the example above.

Image placeholders

An image placeholder is a lightweight version of a target image that can be downloaded quickly, and will occupy the same location as the intended target image, while the target image is still downloading. Once the target image download has been completed the placeholder is replaced with the final image. This feature is especially useful together with large images.

Placeholder images offer the following features:

  • The page loads quickly without blank locations.
  • No page content 'jumping' as the elements dynamically adjust to add downloaded images.

To add a placeholder for a particular image, add the <Placeholder> component within the <Image> component. You can also add the type attribute to the <Placeholder> component to define the type of placeholder to use as follows:

Placeholder type Transformation for the placeholder image
blur (default) A low quality, blurred version of the target image.
pixelate A low quality, pixelated version of the target image.
vectorize A low quality, vectorized version of the target image.
predominant A solid, single color image - the predominant color in the target image.

For example, to use a pixelated placeholder image:

Copy to clipboard
<Image 
  public-id="sample">
  <Placeholder type="pixelate" />
</Image>

You can also combine placeholder images with the lazy loading feature. In this case, when the user scrolls to the image location, the placeholder image is downloaded followed by the target image.

For example, to use a vectorized placeholder image and the lazy loading feature:

Copy to clipboard
<Image 
  public-id="sample" 
  loading="lazy">
  <Placeholder 
    type="vectorize">
  </Placeholder>
</Image>

Image accessibility

The image accessibility feature makes an image more accessible to users that may have a visual disability that impairs their ability to view images.

To enable the accessibility feature for a particular image, add the accessibility attribute to the <Image> component with one of the following modes:

Mode Transformation applied
monochrome Reduces the image to only use one color.
darkmode Adds a dark tinting effect to the image.
brightmode Adds a bright tinting effect to the image.
colorblind Adds an effect to differentiate between colors that are similar.

For example, to assist color blind users:

Copy to clipboard
<Image 
  public-id="sample" 
  accessibility= "colorblind">
</Image>

Advanced image components video tutorial

Watch this video tutorial for an overview on Cloudinary's advanced image components described above: Lazy Loading, Image placeholders and Image accessibility.

Note
The video demonstrates the features in Angular, but the concepts are identical for React.

Applying common image transformations using React

This section provides an overview and examples of the following commonly used image transformation features, along with links to more detailed documentation on these features:

Keep in mind that this section is only intended to introduce you to the basics of using image transformations with React.

For comprehensive explanations of how to implement a wide variety of transformations, see Image transformations. For a full list of all supported image transformations and their usage, see the Image transformation reference.

Resizing and cropping

There are a variety of different ways to resize and/or crop your images, and to control the area of the image that is preserved during a crop.

The following example uses the fill cropping method to generate and deliver an image that completely fills the requested 250x250 size while retaining the original aspect ratio. It uses face detection gravity to ensure that all the faces in the image are retained and centered when the image is cropped:

React:
Copy to clipboard
<Image publicId="family_bench.jpg" >
  <Transformation width="250" height="250" gravity="faces" crop="fill" />
</Image>

Original image before face recognition cropping Original image Fill cropping with 'faces' gravity Fill cropping with 'faces' gravity

For details on all resizing and cropping options, see resizing and cropping images.

Converting to another image format

You can deliver any image uploaded to Cloudinary in essentially any image format. There are three main ways to convert and deliver in another format:

  • Specifying the image's public ID with the desired extension.
  • Explicitly set the desired format using the fetchFormat parameter.
  • Use the value auto to instruct Cloudinary to deliver the image in the most optimized format for each browser that requests it.

For example:

Deliver a .jpg file in .gif format:

React:
Copy to clipboard
<Image publicId="sample.gif" >

</Image>

Let Cloudinary select the optimal format for each browser. For example, in Chrome, this image delivers in .webp format.

React:
Copy to clipboard
<Image publicId="cloud_castle.jpg" >
  <Transformation width="350" fetchFormat="auto" crop="scale" />
</Image>

For more details see image format conversion.

Applying image effects and filters

You can select from a large selection of image effects, enhancements, and filters to apply to your images. The available effects include a variety of color balance and level effects, tinting, blurring, pixelating, sharpening, automatic improvement effects, artistic filters, image and text overlays, distortion and shape changing effects, outlines, backgrounds, shadows, and more.

For example, the code below applies a cartoonify effect, rounding corners effect, and background color effect (and then scales the image down to a height of 300 pixels).

React:
Copy to clipboard
<Image publicId="actor.jpg" >
  <Transformation effect="cartoonify" />
  <Transformation radius="max" />
  <Transformation effect="outline:100" color="lightblue" />
  <Transformation background="lightblue" />
  <Transformation height="300" crop="scale" />
</Image>
An image with several transformation effects

For more details on the available image effects and filters, see Applying image effects and filters.

Adding text and image overlays

You can add images and text as overlays on your main image. You can apply the same types of transformations on your overlay images as you can with any image and you can use gravity settings or x and y coordinates to control the location of the overlays. You can also apply a variety of transformations on text, such as color, font, size, rotation, and more.

For example, the code below overlays a couple's photo on a mug image. The overlay photo is cropped using face detection with adjusted color saturation and a vignette effect applied. The word love is added in a pink, fancy font and rotated to fit the design. A balloon graphic is also added. Additionally, the final image is cropped and the corners are rounded.

React:
Copy to clipboard
<Image publicId="coffee_cup.jpg" >
  <Transformation width="400" height="250" gravity="south" crop="fill" />
  <Transformation overlay="nice_couple" width="1.3" height="1.3" gravity="faces" flags="region_relative" crop="crop" />
  <Transformation effect="saturation:50" />
  <Transformation effect="vignette" />
  <Transformation flags="layer_apply" width="100" radius="max" gravity="center" y="20" x="-20" crop="scale" />
  <Transformation overlay="balloon" height="55" />
  <Transformation effect="hue:-20" angle="5" />
  <Transformation flags="layer_apply" x="30" y="5" />
  <Transformation overlay={{fontFamily: "Cookie", fontSize: 40, fontWeight: "bold", text: "Love"}} effect="colorize" color="#f08" />
  <Transformation angle="20" flags="layer_apply" x="-45" y="44" />
  <Transformation width="300" height="250" x="30" crop="crop" />
  <Transformation radius="60" />
</Image>
An image with many transformations and overlays applied

Image optimizations

By default, Cloudinary automatically performs certain optimizations on all transformed images. There are also a number of additional features that enable you to further optimize the images you use in your React application. These include optimizations to image quality, format, and size, among others.

For example, you can use the auto value for the fetchFormat and quality attributes to automatically deliver the image in the format and quality that minimize file size while meeting the required quality level. Below, these two parameters are applied, resulting in a 50% file size reduction (1.4 MB vs. 784 KB) with no visible change in quality.

React:
Copy to clipboard
<Image publicId="pond_reflect.jpg" >
  <Transformation quality="auto" fetchFormat="auto" />
</Image>
50% file size optimization using auto format and auto quality features

For an in-depth review of the many ways you can optimize your images, see Image optimization.

Responsive image settings

Responsive web design is a method of designing websites to provide an optimal viewing experience to users, irrespective of the device, window size, orientation, or resolution used to view it. Ensuring that optimal experience means you should avoid sending high resolution images that get resized client-side, with significant bandwidth waste for users of small displays. Instead, you should always deliver the right size image for each device and screen size.

Cloudinary can help reduce the complexity with dynamic image transformations. You can simply build image URLs with any image width or height based on the specific device resolution and window size. This means you don't have to pre-create the images, with dynamic resizing taking place on-the-fly as needed.

For example, you can ensure that each user receives images at the size and device pixel ratio (dpr) that fit their device using the auto value for the dpr and width attributes. The auto value is replaced with actual values on the client side based on the actual browser settings and window width:

Copy to clipboard
<Image
  dpr="auto"
  responsive
  width="auto"
  crop="scale"
  responsiveUseBreakpoints="true"
  publicId="myphoto"
  angle="20">
  <Transformation effect="art:hokusai" />
  <Transformation border="3px_solid_rgb:00390b" radius="20" />
</Image>

Besides for a JavaScript based solution, Cloudinary also provides automatic solutions based on the Client-Hints standard. For more information on responsive images and Cloudinary's automatic responsive image solutions, see the detailed documentation on Responsive images.

✔️ Feedback sent!