React SDK


Cloudinary's React SDK provides simple, yet comprehensive image and video upload, transformation, optimization, and delivery capabilities that you can implement using code that integrates seamlessly with your existing React application.

Related topics
This guide relates to the latest released version of the Cloudinary React library.

For details on all new features and fixes from previous versions, see the CHANGELOG.

Quick example

Take a look at the following transformation code and the image it delivers:

Copy to clipboard
<Image publicId="front_face.png" secure="true">
  <Transformation width="150" height="150" gravity="face" crop="thumb" />
  <Transformation radius="20" />
  <Transformation effect="sepia" />
  <Transformation overlay="cloudinary_icon_blue" gravity="south_east" x="5" y="5" width="50" opacity="60" effect="brightness:200" />
  <Transformation angle="10" />
sample transformation

This relatively simple code performs all of the following on the original front_face.jpg image before delivering it:

  • Crop to a 150x150 thumbnail using face-detection gravity to automatically determine the location for the crop
  • Round the corners with a 20 pixel radius
  • Apply a sepia effect
  • Overlay the Cloudinary logo on the southeast corner of the image (with a slight offset). The logo is scaled down to a 50 pixel width, with increased brightness and partial transparency (opacity = 60%)
  • Rotate the resulting image (including the overlay) by 10 degrees
  • Convert and deliver the image in PNG format (the originally uploaded image was a JPG)

And here's the URL that would be included in the image tag that's automatically generated from the above code:

React SDK features

  • Build URLs for image and video transformation & manipulation
  • Helper elements for embedding and transforming images, and more

Installation and Setup

1. Install the React SDK

The Cloudinary React SDK serves as a layer on top of Cloudinary's Javascript (cloudinary-core) library. Install the SDKs by running the following command:

Copy to clipboard
npm install cloudinary-react --save

2. Include the required elements of the cloudinary-react library in your code

The following 4 elements are available:

Copy to clipboard
import {Image, Video, Transformation, CloudinaryContext} from 'cloudinary-react';
  • CloudinaryContext - allows you to define shared parameters that are applied to all child elements.
  • Image - defines a Cloudinary Image tag.
  • Video - defines a Cloudinary Video tag.
  • Transformation - allows you to define additional transformations on the parent element.

3. Set Cloudinary configuration parameters.

To use the Cloudinary React elements, you must configure at least your Cloudinary account cloudName. You can additionally define a number of optional configuration parameters if relevant. You can find your account-specific configuration credentials in the dashboard of our Management Console. You can apply these settings directly to each element, or you can apply them to all child elements using a CloudinaryContext element.

For example:

  • Configuration directly in the element:
Copy to clipboard
<Image cloudName="demo" publicId="sample" width="300" crop="scale" />
  • Configuration with CloudinaryContext applies to all child elements:
Copy to clipboard
<CloudinaryContext cloudName="demo">
    <Image publicId="sample" width="50" crop="scale" />
  <Image publicId="sample" width="0.5" crop="scale" />

Using core Cloudinary JavaScript features

The Cloudinary JavaScript library is the foundation library underlying Cloudinary's React SDK. You can access any of the core JavaScript functionality within your React code after importing the core library. For example:

Copy to clipboard
import {Cloudinary} from 'cloudinary-core';
const cloudinaryCore = new cloudinary.Cloudinary({cloud_name: 'demo'});
const SampleImg = () => (
    <img src={cloudinaryCore.url('sample')} />

React capitalization and data type guidelines

When using the React SDK, keep these guidelines in mind:

  • Parameter names: camelCase. For example: publicId
  • Classes: PascalCase. For example: ImageTag
  • Methods: camelCase. For example: toHTML
  • Pass parameter data as: Object


See our React sample projects for example code to help you get started:

✔️ Feedback sent!