React SDK v2 (Beta)

Important
The React frontend framework library is currently in BETA. There may be minor changes to parameter names or other implementation details before the general access release. We invite you to try it out. We would appreciate any feedback via our support team.

  • Video rendering is not supported in this release.

Quick start

If you're ready to get coding, jump straight to our Quickstart guide. Otherwise, keep reading to get a more in-depth understanding of the React frontend framework library.

Overview

Cloudinary's React frontend framework library provides image rendering capabilities and plugins 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, released from the frontend-frameworks GitHub repository.

  • For details on all new features and fixes from previous versions, see the CHANGELOG.
  • See the React migration guide for information on migrating to Cloudinary's React SDK v2.

Architecture

The React frontend framework library must be used in conjunction with the JavaScript js-url-gen library to provide all of Cloudinary's transformation and optimization functionality.

Two GitHub repositories provide all the functionality:

  • js-url-gen contains all the functionality required to create delivery URLs for your Cloudinary assets based on the configuration and transformation actions that you specify. All the js-url-gen functionality is installed through the @cloudinary/url-gen package.
  • frontend-frameworks contains the framework libraries and plugins that can be used to render images and videos on your site. There are different installation packages for each framework, so for example, React is installed through @cloudinary/react, and Angular is installed through @cloudinary/angular.

Full example

This example shows a transformation URL being created using the @cloudinary/url-gen package, and rendered using React. It demonstrates the use of tree shaking to reduce the bundle size, which explains why there are so many import statements.

Copy to clipboard
import React from 'react'
import {AdvancedImage} from '@cloudinary/react';
import {Cloudinary} from "@cloudinary/url-gen";
import {Transformation} from "@cloudinary/url-gen";

// Import required actions.
import {thumbnail, scale} from "@cloudinary/url-gen/actions/resize";
import {byRadius} from "@cloudinary/url-gen/actions/roundCorners";
import {sepia} from "@cloudinary/url-gen/actions/effect";
import {source} from "@cloudinary/url-gen/actions/overlay";
import {opacity,brightness} from "@cloudinary/url-gen/actions/adjust";
import {byAngle} from "@cloudinary/url-gen/actions/rotate"

// Import required qualifiers.
import {image} from "@cloudinary/url-gen/qualifiers/source";
import {Position} from "@cloudinary/url-gen/qualifiers/position";
import {compass} from "@cloudinary/url-gen/qualifiers/gravity";

const App = () => {

  // Create and configure your Cloudinary instance.
  const cld = new Cloudinary({
    cloud: {
      cloudName: 'demo'
    }
  }); 

  // Use the image with public ID, 'front_face'.
  const myImage = cld.image('front_face');

  // Apply the transformation.
  myImage
  .resize(thumbnail().width(150).height(150).gravity('face'))  // Crop the image.
  .roundCorners(byRadius(20))    // Round the corners.
  .effect(sepia())  // Apply a sepia effect.
  .overlay(   // Overlay the Cloudinary logo.
    source(
      image('cloudinary_icon_blue')
        .transformation(new Transformation()
        .resize(scale(50)) // Resize the logo.
          .adjust(opacity(60))  // Adjust the opacity of the logo.
        .adjust(brightness(200)))  // Adjust the brightness of the logo.       
    )
    .position(new Position().gravity(compass('south_east')).offsetX(5).offsetY(5))   // Position the logo.
  )
  .rotate(byAngle(10))  // Rotate the result.
  .format('png');   // Deliver as PNG. */

  // Render the transformed image in a React component.
  return (
    <div>
      <AdvancedImage cldImg={myImage} />
    </div>
  )
};

sample transformation

This code creates the URL required to deliver the front_face.jpg image with the following transformations applied:

  • 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 is generated from the above code:

Learn more about transformations

Get started with React

Installation

Install Cloudinary's JavaScript and React packages using the NPM package manager:

Copy to clipboard
npm i @cloudinary/url-gen @cloudinary/react --save

Configuration

You can specify the configuration parameters that are used to create the delivery URLs, either using a Cloudinary instance or per image/video.

Note
Specify the configuration parameters in camelCase, for example cloudName.

Cloudinary instance configuration

If you want to use the same configuration to deliver all your media assets, it's best to set up the configuration through a Cloudinary instance, for example:

Copy to clipboard
import React from 'react'
import {AdvancedImage} from '@cloudinary/react';
import {Cloudinary} from "@cloudinary/url-gen";

const App = () => {

  // Create a Cloudinary instance and set your cloud name.
  const cld = new Cloudinary({
    cloud: {
      cloudName: 'demo'
    }
  });

  // cld.image returns a CloudinaryImage with the configuration set.
  const myImage = cld.image('sample');

  // The URL of the image is: https://res.cloudinary.com/demo/image/upload/sample

  // Render the image in a React component.
  return (
    <div>
      <AdvancedImage cldImg={myImage} />
    </div>
  )
};

You can set other configuration parameters related to your cloud and URL as required, for example, if you have your own custom domain name, and want to generate a secure URL (HTTPS):

Copy to clipboard
// Create a Cloudinary instance, setting some Cloud and URL configuration parameters.
const cld = new Cloudinary({
  cloud: {
    cloudName: 'demo'
  },
  url: {
    secureDistribution: 'www.example.com', 
    secure: true 
  }
});

// This creates a URL of the form: https://www.example.com/demo/image/upload/sample

Asset instance configuration

If you need to specify different configurations to deliver your media assets, you can specify the configuration per image/video instance, for example:

Copy to clipboard
import React from 'react'
import {AdvancedImage} from '@cloudinary/react';
import {CloudinaryImage} from "@cloudinary/url-gen/assets/CloudinaryImage";
import URLConfig from "@cloudinary/url-gen/config/URLConfig";
import CloudConfig from "@cloudinary/url-gen/config/CloudConfig";

const App = () => {

  // Set the Cloud configuration and URL configuration
  let cloudConfig = new CloudConfig({cloudName: 'demo'});
  let urlConfig = new URLConfig({secure: true});

  // Instantiate and configure a CloudinaryImage object.
  let myImage = new CloudinaryImage('docs/shoes', cloudConfig, urlConfig);

  // The URL of the image is: https://res.cloudinary.com/demo/image/upload/docs/shoes

  // Render the image in a React component.
  return (
    <div>
      <AdvancedImage cldImg={myImage} />
    </div>
  )
};

Transformations

The @cloudinary/url-gen package simplifies the generation of transformation URLs, and includes special components and directives for easy embedding of assets in your React application.

Image with several transformations applied

To find out more about transforming your assets using the @cloudinary/url-gen package, see:

Plugins

The Cloudinary React library provides plugins to render the media on your site in the most optimal way and improve your user's experience by automating media tasks like lazy loading, responsive images and more.

Sample projects

Try out the examples in these code explorers:

✔️ Feedback sent!

Rate this page: