> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# React SDK

[alternative-transformations-link]:react_image_transformations#alternative_ways_to_apply_transformations
[sample-projects-link]:react_sample_projects
[changelog-link]: https://github.com/cloudinary/frontend-frameworks/blob/master/CHANGELOG.md

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

## How would you like to learn?

{table:class=no-borders overview}Resource | Description 
--|--
[React Starter Kit](react_starter_kit) | A ready-to-use, fully functional React app integrating Cloudinary upload and delivery features. Ideal for new projects and fast prototyping with AI assistance.
[React quick start](react_quick_start) | Get up and running in five minutes with a walk through of installation, configuration, rendering, and transformations. Ideal for existing projects and hands-on learning.
[Video tutorials](react_video_tutorials) | Watch tutorials relevant to your use cases, from getting started with the React SDK, to rendering and transforming your images and videos. 
[Sample projects](react_sample_projects) | Explore sample projects to see how to implement Cloudinary functionality such as rendering and delivery with transformations.
[Cloudinary React SDK GitHub repo](https://github.com/cloudinary/frontend-frameworks/tree/master/packages/react) | Explore the source code and see the [frontend-frameworks][changelog-link] and [js-url-gen](https://github.com/cloudinary/js-url-gen/blob/master/CHANGELOG.md) CHANGELOGS for details on all new features and fixes from previous versions. 
 | Try the free [Introduction to Cloudinary for React Developers](https://training.cloudinary.com/courses/introduction-to-cloudinary-using-the-react-sdk-50-minute-course) online course, where you can learn how to render, transform and optimize your digital assets.

Other helpful resources...

This guide focuses on how to set up and implement popular Cloudinary capabilities using the React SDK, but it doesn't cover every feature or option. Check out these other resources to learn about additional concepts and functionality in general. 

{table:class=no-borders overview}Resource | Description 
--|--
[Developer kickstart](dev_kickstart) |A hands-on, step-by-step introduction to Cloudinary features.
[Glossary](cloudinary_glossary) | A helpful resource to understand Cloudinary-specific terminology.
[Guides](programmable_media_guides) | In depth guides to help you understand the many, varied capabilities provided by the product. 
[References](cloudinary_references) | Comprehensive references for all APIs, including React code examples.

## Install

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

```
npm i @cloudinary/url-gen @cloudinary/react
```

If you prefer not to use a bundler, you can [import the packages directly from a CDN](#cdn_import).

Why two packages?

You must use the React frontend framework library in conjunction with the JavaScript [js-url-gen](javascript_integration) library to provide all of Cloudinary's transformation and optimization functionality.
 Two GitHub repositories provide all the functionality:

* [js-url-gen](https://github.com/cloudinary/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](https://github.com/cloudinary/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`, the Angular SDK is installed through `@cloudinary/ng` and the Vue.js SDK is installed through `@cloudinary/vue`.

## Configure

Include Cloudinary's React and JavaScript classes in your code:

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

> **TIP**: :title=CDN import

If you prefer not to use a bundler, you can import the packages directly from a CDN using ESM-compatible URLs:

```react
import { Cloudinary } from 'https://cdn.jsdelivr.net/npm/@cloudinary/url-gen/+esm';
import { AdvancedImage, AdvancedVideo } from 'https://cdn.jsdelivr.net/npm/@cloudinary/react/+esm';
```

### Set required configuration parameters

You can set the required configuration parameter, `cloudName`, either when creating a [Cloudinary instance](#cloudinary_instance_configuration) or [per asset](#asset_instance_configuration).

#### 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:

```react
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>
  )
};
```

#### 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:

```react
import React from 'react'
import {AdvancedImage} from '@cloudinary/react';
import {CloudinaryImage} from "@cloudinary/url-gen";
import {URLConfig} from "@cloudinary/url-gen";
import {CloudConfig} from "@cloudinary/url-gen";

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>
  )
};
```

### Set additional configuration parameters

In addition to the required configuration parameters, you can define a number of optional [configuration parameters](cloudinary_sdks#configuration_parameters) if relevant.

> **NOTE**: Specify all configuration parameters in `camelCase`, for example **secureDistribution**.

You can use the Cloudinary constructor to set configuration parameters, for example:

```react

// 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
```

### Configuration video tutorials

The following tutorials can help you install and set up your SDK:

  
  
  
    Find Your Credentials
    Find your Cloudinary credentials for APIs and SDKs 
  

  
  
  
    Configure the React SDK
    Install and configure the Cloudinary React SDK 
  

See more [React video tutorials](react_video_tutorials).

## Use

Once you've installed and configured the React SDK, you can use it for:

* **Transforming images** - Render your images with transformations applied, using the `AdvancedImage` component. [See examples](#quick_examples_image_transformations)
* **Transforming videos** - Render your videos with transformations applied, using the `AdvancedVideo` component. [See examples](#quick_examples_video_transformations)
* **Optimizing delivery** - Use plugins to improve your user's experience by automating media tasks like lazy loading, responsive images and more. [See plugins](#plugins)

### Quick examples: Image transformations

Here are two quick examples to get you started with image transformations:

* [Image transformation example 1](#image_transformation_example_1) - Apply a sepia effect to an image
* [Image transformation example 2](#image_transformation_example_2) - Apply multiple transformations as chained transformations

#### Image transformation example 1

The following React code renders the front_face.jpg image with a sepia effect applied:

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

// Import required actions.
import {sepia} from "@cloudinary/url-gen/actions/effect";

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
  .effect(sepia());  // Apply a sepia effect.

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

```

This code creates the HTML required to render the following transformation URL:

![Sample image transformation](https://res.cloudinary.com/demo/image/upload/e_sepia/front_face "with_url:true, with_code:false, thumb: c_scale,w_150")

#### Image transformation example 2

You can apply more than one transformation at a time (see [chained transformations](image_transformations#chained_transformations)) to give more interesting results (notice how you import only the actions and qualifiers that you need, to [minimize your bundle size](react_image_transformations#tree_shaking)):

![Sample image transformation](https://res.cloudinary.com/demo/image/upload/c_thumb,g_face,h_150,w_150/r_20/e_sepia/l_cloudinary_icon/e_brightness:90/o_60/c_scale,w_50/fl_layer_apply,g_south_east,x_5,y_5/a_10/q_auto/front_face.png "disable_all_tab: true, with_url: false, frameworks:react_2")

```react
new CloudinaryImage("front_face.png")
  .resize(
    thumbnail()
      .width(150)
      .height(150)
      .gravity(focusOn(face()))
  )
  .roundCorners(byRadius(20))
  .effect(sepia())
  .overlay(
    source(
      image("cloudinary_icon").transformation(
        new Transformation()
          .adjust(brightness().level(90))
          .adjust(opacity(60))
          .resize(scale().width(50))
      )
    ).position(
      new Position()
        .gravity(compass("south_east"))
        .offsetX(5)
        .offsetY(5)
    )
  )
  .rotate(byAngle(10))
  .delivery(quality(auto()));
```

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). Scale the logo overlay down to a 50 pixel width, with increased brightness and partial transparency (opacity = 60%).
* **Rotate** the resulting image (including the overlay) by 10 degrees
* **Optimize** the image to reduce the size of the image without impacting visual quality.
* **Convert** and deliver the image in PNG format (the originally uploaded image was a JPG)

And here's the URL that's automatically generated and rendered from the above code:

![Sample image transformation](https://res.cloudinary.com/demo/image/upload/c_thumb,g_face,h_150,w_150/r_20/e_sepia/l_cloudinary_icon/e_brightness:90/o_60/c_scale,w_50/fl_layer_apply,g_south_east,x_5,y_5/a_10/q_auto/front_face.png "disable_all_tab: true, with_code:false, with_image:false")
The `@cloudinary/url-gen` package installs an additional [transformation-builder-sdk](https://github.com/cloudinary/js-transformation-builder-sdk) library as a dependency, which handles the transformation generation part of the URL. 

You can use the [Transformation Builder reference](https://cloudinary.com/documentation/sdks/js/transformation-builder/index.html) to find all available transformations, syntax and examples.> **TIP**: There are [alternative ways to apply transformations][alternative-transformations-link] to your images, for example:

```js
import { transformationStringFromObject } from "@cloudinary/url-gen";

const transformation = transformationStringFromObject([
  {gravity: "face", height: 150, width: 150, crop: "thumb"},
  {radius: 20},
  {effect: "sepia"},
  {overlay: "cloudinary_icon"},
  {width: 50, crop: "scale"},
  {opacity: 60},
  {effect: "brightness:90"},
  {flags: "layer_apply", gravity: "south_east", x: 5, y: 5},
  {angle: 10},
  {fetch_format: "png"}
  ]);
myImage.addTransformation(transformation);
```
> **Learn more about image transformations**:
>
> * Read the [image transformation guide](image_transformations) to learn about the different ways to transform your images.

> * See more examples of [image transformations](react_image_transformations) using the Cloudinary React SDK.  

> * See all possible transformations in the [Transformation URL API reference](transformation_reference).

> * See all JavaScript transformation actions and qualifiers in the [Transformation Builder reference](https://cloudinary.com/documentation/sdks/js/transformation-builder/list_namespace.html).

### Quick examples: Video transformations

Here are two quick examples to get you started with video transformations:

* [Video transformation example 1](#video_transformation_example_1) - Adjust the brightness of a video
* [Video transformation example 2](#video_transformation_example_2) - Apply multiple transformations as chained transformations

#### Video transformation example 1

The following React code renders the ship.mp4 video with a brightness adjustment applied:

```react
import React from 'react'
import {AdvancedVideo} from '@cloudinary/react';
import {Cloudinary} from "@cloudinary/url-gen";

// Import required actions.
import {brightness} from "@cloudinary/url-gen/actions/adjust";

const App = () => {

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

  // Use the video with public ID, 'ship'.
  const myVideo = cld.video('ship');

  // Apply the transformation.
  myVideo
  .adjust(brightness().level(20));  // Adjust brightness.

  // Render the transformed video in a React component.
  return (
    <div>
      <AdvancedVideo cldVid={myVideo} controls />
    </div>
  )
};

```

This code creates the HTML required to render the following transformation URL:

![Sample video transformation](https://res.cloudinary.com/demo/video/upload/e_brightness:20/ship.mp4 "with_url:true, with_code:false, thumb: c_scale,w_300")

#### Video transformation example 2

You can apply more than one transformation at a time (see [chained transformations](video_manipulation_and_delivery#chained_transformations)) to give more interesting results (notice how you import only the actions and qualifiers that you need, to [minimize your bundle size](react_video_transformations#tree_shaking)):

![Sample video transformation](https://res.cloudinary.com/demo/video/upload/ar_1:1,c_fill,g_auto,w_300/e_blur:50/r_max/ship.mp4 "disable_all_tab: true, with_url: false, frameworks:react_2")

```react
new CloudinaryVideo("ship.mp4")
  .resize(
    fill()
      .width(300)
      .aspectRatio(ar1X1())
      .gravity(autoGravity())
  )
  .effect(blur().strength(50))
  .roundCorners(max());
```

This relatively simple code performs all of the following on the original ship.mp4 video before delivering it:

* **Crop** to a 1:1 aspect ratio (square) with a width of 300 pixels, using automatic gravity to determine the focal point
* Apply a **blur effect** with strength 50
* Apply **maximum rounding** to create a circular video

And here's the URL that's automatically generated and rendered from the above code:

![Sample video transformation](https://res.cloudinary.com/demo/video/upload/ar_1:1,c_fill,g_auto,w_300/e_blur:50/r_max/ship.mp4 "disable_all_tab: true, with_code:false, with_image:false")

Similar to [image transformations](#quick_examples_image_transformations), there are [alternative ways to apply transformations](react_video_transformations#alternative_ways_to_apply_transformations) to your videos.

> **Learn more about video transformations**:
>
> * Read the [video transformation guide](video_manipulation_and_delivery) to learn about the different ways to transform your videos.

> * See more examples of [video transformations](react_video_transformations) using the Cloudinary React SDK.  

> * See all possible transformations in the [Transformation URL API reference](transformation_reference).

> * See all JavaScript transformation actions and qualifiers in the [Transformation Builder reference](https://cloudinary.com/documentation/sdks/js/transformation-builder/list_namespace.html).

### Plugins

The Cloudinary React SDK provides [plugins](react_image_transformations#plugins) to render the media on your site in the optimal way and improve your user's experience by automating media tasks like lazy loading, responsive images and more.

> **Learn more about plugins**:
>
> * See how to use [image plugins](react_image_transformations#plugins) and [video plugins](react_video_transformations#plugins) in your React application.

 
## Sample projects
Take a look at the [React sample projects][sample-projects-link] page to help you get started integrating Cloudinary into your React application.> **TIP**: Check out our collection of [React code explorers](code_explorers) too!

> **READING**:
>
> * Try out the React SDK using the [quick start](react_quick_start).   

> * See examples of powerful [image](react_image_transformations) and [video](react_video_transformations) transformations using React code, and see our [image transformation](image_transformations) and [video transformation](video_manipulation_and_delivery) docs.   

> * For details on migrating to this SDK from the legacy React SDK, see the [React migration guide](react1_migration_guide).

> * For information about uploading images and videos from a React application, see [React image and video upload](react_image_and_video_upload).

> * Stay tuned for updates by following the [Release Notes](programmable_media_release_notes) and the [Cloudinary Blog](https://cloudinary.com/blog).