The Cloudinary JavaScript 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 JavaScript or JS-based framework application.
This guide describes Cloudinary's
js-url-gen frontend library.
- For the backend Node.js library, which also covers upload and admin functionality, see the Node.js documentation.
- If you're using a frontend framework, jump straight to the relevant docs:
If you're using pure frontend JavaScript without one of the above frameworks, follow the instructions on this page for installation and setup.
| Resource |
Description |
| JavaScript quick start |
Get up and running in five minutes with a walk through of installation, configuration, rendering, and transformations. |
| Video tutorials |
Watch tutorials relevant to your use cases, from getting started with the JavaScript SDK, to rendering and transforming your images and videos. |
| Sample projects |
Explore sample projects to see how to implement Cloudinary functionality such as rendering and delivery with transformations. |
| Cloudinary js-url-gen GitHub repo |
Explore the source code and see the CHANGELOG for details on all new features and fixes from previous versions. |
Install the @cloudinary/url-gen package using the NPM package manager:
If you prefer not to use a bundler, you can import the SDK directly from a CDN.
Include Cloudinary's JavaScript classes in your code:
If you prefer not to use a bundler, you can import the SDK directly from a CDN using an ESM-compatible URL:
You can set the required configuration parameter, cloudName, either when creating a Cloudinary instance or per asset.
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:
If you need to specify different configurations to deliver your media assets, you can specify the configuration per image/video instance, for example:
In addition to the required configuration parameters, you can define a number of optional configuration parameters if relevant.
Specify all configuration parameters in
camelCase, for example
secureDistribution.
You can use the Cloudinary constructor to set configuration parameters, for example:
Some build environments require additional configuration:
-
Rollup + Vanilla JS: install and use
@rollup/node-resolve.
-
Next.js + Vanilla JS: install and use
moxystudio/next-compile-node-modules (or some other similar solution).
-
TypeScript + Webpack: set
"moduleResolution": "node" in the TSConfig file.
The following tutorials can help you install and set up your SDK:
See more JavaScript video tutorials.
Once you've installed and configured the JavaScript SDK, you can use it for:
-
Transforming images - Generate transformation URLs for your images. See examples
-
Transforming videos - Generate transformation URLs for your videos. See examples
-
Optimizing delivery - Use plugins to improve your user's experience by automating media tasks like lazy loading, responsive images and more. See plugins
Here are two quick examples to get you started with image transformations:
The following Javascript code renders the front_face.jpg image with a sepia effect applied:
This code creates the HTML required to render the following transformation URL:
You can apply more than one transformation at a time (see chained transformations) to give more interesting results (notice how you import only the actions and qualifiers that you need, to minimize your bundle size):
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:
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.
Learn more about image transformations
Here are two quick examples to get you started with video transformations:
The following Javascript code renders the ship.mp4 video with a brightness adjustment applied:
This code creates the HTML required to render the following transformation URL:
You can apply more than one transformation at a time (see chained transformations) to give more interesting results (notice how you import only the actions and qualifiers that you need, to minimize your bundle size):
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:
Similar to image transformations, there are alternative ways to apply transformations to your videos.
Learn more about video transformations
The @cloudinary/html package from frontend-frameworks provides 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.
Take a look at the JavaScript sample projects page to help you get started integrating Cloudinary into your JavaScript application.
