React Native SDK
Last updated: Jun-12-2024
This page provides an in-depth introduction to the Cloudinary React Native library. The library allows you to integrate Cloudinary URL generation functionality and load your Cloudinary images in your native Android and iOS apps.
Overview
Cloudinary's React Native library provides image rendering capabilities and plugins that you can implement in your React Native apps.
The React Native SDK has a dependency on the Expo module. If you're not using Expo in your project, you will need to install the module separately in order to use the SDK.
Quick example
This example shows a transformation URL being created using the @cloudinary/url-gen
package, and rendered using React Native.
import React from 'react';
import { SafeAreaView } from 'react-native';
import { AdvancedImage } from 'cloudinary-react-native';
import { Cloudinary } from "@cloudinary/url-gen";
// Import required actions.
import { sepia } from "@cloudinary/url-gen/actions/effect";
export default function 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 Native component.
return (
<SafeAreaView style={{flex: 1, justifyContent: 'center'}}>
<AdvancedImage cldImg={myImage} style={{ width: 200, height: 200, alignSelf: 'center'}} />
</SafeAreaView>
)
};
This code creates the HTML required to deliver the front_face.jpg image with the sepia effect applied.
You can apply more than one transformation at a time (see chained transformations) to give more interesting results:
- 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)
There are alternative ways to apply transformations to your images, for example:
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);
- See all possible transformations in the Transformation URL API reference.
- See all JavaScript transformation actions and qualifiers in the Transformation Builder reference.
- See more examples of image transformations using the
js-url-gen v1.x
library.
Get started with React Native
Installation
Install Cloudinary's React Native package using the NPM package manager:
npm i cloudinary-react-native
Configuration
You can specify the configuration parameters that are used to create the delivery URLs, either using a Cloudinary instance or per image.
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:
import React from 'react';
import { SafeAreaView } from 'react-native';
import { AdvancedImage } from 'cloudinary-react-native';
import { Cloudinary } from "@cloudinary/url-gen";
// Create a Cloudinary instance and set your cloud name.
const cld = new Cloudinary({
cloud: {
cloudName: 'demo'
}
});
export default function App() {
// 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 (
<SafeAreaView>
<AdvancedImage cldImg={myImage} style={{ width: 300, height: 200 }} />
</SafeAreaView>
)
};
You can set other configuration parameters related to your cloud and URL as required, for example, if you have your own custom delivery hostname, and want to generate a secure URL (HTTPS):
// 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 instance, for example:
import React from 'react';
import { SafeAreaView } from 'react-native';
import { AdvancedImage } from 'cloudinary-react-native';
import { CloudinaryImage } from "@cloudinary/url-gen";
import { URLConfig } from "@cloudinary/url-gen";
import { CloudConfig } from "@cloudinary/url-gen";
// Set the Cloud configuration and URL configuration
let cloudConfig = new CloudConfig({ cloudName: 'demo' });
let urlConfig = new URLConfig({ secure: true });
export default function App() {
// 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 (
<SafeAreaView>
<AdvancedImage cldImg={myImage} style={{ width: 300, height: 200 }} />
</SafeAreaView>
)
};
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 Native application.
The @cloudinary/url-gen
package installs an additional transformation-builder-sdk library as a dependency, which handles the transformation generation part of the URL.
You can use the Transformation Builder reference to find all available transformations, syntax and examples.
To find out more about transforming your assets using the @cloudinary/url-gen
package, see React image transformations