React SDK v1

Overview

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.

Tip
In this guide you'll learn how to get started with the React SDK, but if you are not familiar with Cloudinary, we advise reading How to integrate Cloudinary first for a high-level overview of integrating Cloudinary into your code, and an introduction to the main concepts.

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

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

If you haven't already started integrating this SDK, you may want to try the JavaScript SDK v2 (Beta) together with the React frontend framework library (Beta).

Quick example

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

React:
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" />
</Image>
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:

In a similar way, you can transform a video.

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.

Note
Most functionality implemented on the client side does not require authentication, so only your cloud name is required to be configured, and not your API key or secret. Your API secret should never be exposed on the client side, so if you want to use signed uploads or generate delivery signatures, you’ll also need server-side code, for which you can use one of our server-side SDKs.

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">
  <div>
    <Image publicId="sample" width="50" crop="scale" />
  </div>
  <Image publicId="sample" width="0.5" crop="scale" />
</CloudinaryContext>

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

Samples

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

✔️ Feedback sent!

Rate this page: