Studio widget

The Studio widget embeds Cloudinary Studio in your web application, so your users can crop, resize, and transform images, and apply AI-driven edits, without leaving your platform. When they finish, the widget returns the delivery URL of the transformed image to your application.

The widget runs inside an iframe, and integrating it takes a script tag and a few lines of JavaScript.

When to use the Studio widget

Use the Studio widget when your users manage images in your platform and need to edit them for delivery, for example:

• Product information management (PIM) and e-commerce platforms: Merchandisers crop product images to the required aspect ratio, fix swatches, or remove backgrounds while editing a product listing.
• Page builders and CMSs: Content editors adjust an image to fit a page layout and insert the resulting URL directly into the page. For example, the Salesforce Commerce Cloud Page Designer Cartridge uses the Studio widget so editors can transform images without leaving Page Designer.

If your users need to browse, search, and select assets from their Media Library, use the Media Library widget instead.

How to integrate the widget in your app

1. Include the required JavaScript

Add the following script to the page where you want to open the Studio widget:

The latest path always loads the most recent version of the widget, including the latest features and fixes. To control when your integration picks up changes, you can replace latest with a specific version number, for example https://studio-widget.cloudinary.com/1.0.14/all.js. Call getVersion() to check which version is loaded.

Once loaded, the widget is available as window.cloudinary.studioWidget.

2. Create the widget

Call cloudinary.studioWidget() with your cloud name, the element to mount the widget in, and either an API key or an OAuth token for authentication:

If your users are already logged in to Cloudinary through your application using OAuth, pass their access token instead of the API key:

See Constructor options for all available options.

3. Load an asset and open the widget

Use update() to set the images and, optionally, a transformation to start from, then call show() to open the widget:

4. Handle events

Listen for the insert event to receive the delivery URL of the transformed image when the user clicks Insert, and for the close event to respond when the user closes the widget:

Reopen the widget for a different asset

The widget saves the user's editing session, including applied transformations and selected assets, and restores it the next time it opens. When you reopen the widget for a different asset, call show() with resetState: true so the previous session's transformations aren't applied to the new asset:

The resetState option applies only to that call. A later show() without the option restores the saved session as usual.

Configuration options

Constructor options

Pass these options to cloudinary.studioWidget().

Feature configuration

Pass these options in the featureConfig object of the constructor. All options are Boolean.

For example, to open the widget in manual crop mode with automatic format and quality, and without its own close button:

Sample app

The Studio widget sample app is a static JavaScript app that opens the Studio widget for an image you choose, then displays the transformed image and its delivery URL when you click Insert. Add your own cloud name and API key to studio-widget.js to run it.

Fork the repo and try it yourself

The code for this app is available in GitHub.

• Enjoy interactive learning? Check out more sample apps!