Ask AI
Studio Widget API reference
Last updated: Nov-04-2026
The Studio Widget API reference details the options, methods, and events that you can use when embedding the Studio Widget in your web application.
- For integration steps and use cases, see the Studio Widget guide.
- Check out the Studio Widget sample app to see a complete implementation in JavaScript.
Installation
To use the Studio Widget, include the Studio Widget JavaScript file in your HTML:
The latest path always loads the most recent version of the widget. To load a specific version, replace latest with the version number, for example https://studio-widget.cloudinary.com/1.0.15/all.js. See the changelog for the available versions.
Once loaded, the widget is available as window.cloudinary.studioWidget.
Initialization
studioWidget
Creates a Studio Widget instance and returns it. The widget isn't displayed until you call show().
Syntax
cloudinary.studioWidget(options)
| Parameter | Type | Description |
|---|---|---|
| options | Object | Required. The constructor options, including the cloud name, authentication, mount element, and feature configuration. |
Example
Configuration options
Constructor options
Pass these options to cloudinary.studioWidget().
| Option | Type | Description |
|---|---|---|
cloudName |
String | Required. The cloud name of the product environment to access. |
appendTo |
String or HTMLElement |
Required. A DOM selector, for example '#my-container', or the HTML element to mount the widget iframe in. |
apiKey |
String | The API key of the product environment, used to authenticate when loading the widget. |
oauthToken |
String | An OAuth access token to authenticate with, instead of an API key. See Using OAuth to access Cloudinary APIs. |
iframeAttr |
Object | Additional attributes to set on the iframe element, for example id, title, or custom styles. Merged with the default attributes. |
featureConfig |
Object | Controls which features are visible or enabled in the widget. See Feature configuration. |
Feature configuration
Pass these options in the featureConfig object of the constructor. All options are Boolean.
| Option | Default | Description |
|---|---|---|
hideDownloadAssetButton |
true | Hides the download asset button. |
hideSaveAssetButton |
true | Hides the Save Asset button, which lets the user save the transformed image as a new asset or overwrite the original. The options available depend on the user's permissions. |
hideSaveTemplateButton |
true | Hides the save template button. |
hideCloseButton |
false | Hides the widget's close (X) button. Use this when your application provides its own close control. |
hideDeliveryTab |
true | Hides the Get Code tab. |
hideTemplatesTab |
true | Hides the Templates tab, which lists saved Studio templates that the user can apply to the image. |
hideAiChatTab |
true | Hides the AI Chat tab. |
hideWelcomeModal |
true | Hides the welcome modal when the widget first loads. |
showInsertButton |
true | Shows the Insert button, which triggers the insert event. Your application receives the delivery URL of the transformed image in the event callback. |
showIntercomFeedbackButton |
false | Shows the feedback button. |
canUseRefiners |
false | Enables refiners. |
canChangePreviewImage |
false | Allows the user to change the preview image. |
advancedCodeSnippet |
false | Enables copying code and SDK code previews in the Get Code tab. |
startWithManualCrop |
false | Opens the widget in manual crop mode. |
f_auto |
false | Adds f_auto (automatic format) to the delivery URL. |
q_auto |
false | Adds q_auto (automatic quality) to the delivery URL. |
ignoreUnsavedChanges |
true | Hides the unsaved changes label and skips the confirmation when the user closes the widget. |
Instance methods
After you create the widget with studioWidget(), use the following methods to control and interact with it.
show
Creates the widget iframe with the latest configuration and makes it visible. Each call creates a fresh iframe, and registered event listeners are preserved.
The widget saves the user's editing session in the browser, including applied transformations and selected assets, and restores it the next time it opens. Closing the widget with its close button clears the saved session. Pass resetState: true to discard the saved session, for example when reopening the widget for a different asset.
Syntax
widget.show(options)
| Parameter | Type | Description |
|---|---|---|
| options | Object | Optional. Settings for this call only. Supported option: resetState (Boolean). When true, the widget opens with the current update() configuration and discards the saved editing session. A later show() without the option restores the saved session as usual. |
Example
hide
Hides the widget iframe.
resetState: true.Syntax
widget.hide()
Example
update
Sets the images and transformation for the widget to load. The configuration is stored and applied the next time you call show(). Successive calls are merged, so each call extends the previous configuration.
Syntax
widget.update(config)
| Parameter | Type | Description |
|---|---|---|
| config | Object | Required. The configuration to apply. See the options below. |
The config object supports the following options:
| Option | Type | Description |
|---|---|---|
publicIds |
Array of strings | The public IDs of the images to load in the widget. |
transformation |
String | A transformation to apply when the widget loads, in transformation URL syntax, for example c_fill,g_auto,h_500,w_500. |
Example
destroy
Removes the widget iframe and all event listeners, and cleans up resources. Don't use the widget instance after calling destroy(). To open the widget again, create a new instance with studioWidget().
Syntax
widget.destroy()
Example
on
Registers a handler for a widget event. Listeners are preserved across show() calls.
Syntax
widget.on(event, callback)
| Parameter | Type | Description |
|---|---|---|
| event | String | The name of the event to listen for. Supported values: insert, close
|
| callback | Function | The function to call when the event is triggered. For the insert event, it receives the delivery URL of the transformed image. |
Example
getVersion
Returns the version of the loaded Studio Widget script.
Syntax
widget.getVersion()
Example
Events
Register handlers for these events with the on() method. The widget stays visible after both events, so call hide() in your handler to remove it from view.
| Event | Description | Callback data |
|---|---|---|
insert |
Triggered when the user clicks Insert. Requires showInsertButton to be true (default). |
The delivery URL of the transformed image, as a string. |
close |
Triggered when the user clicks the widget's close button. Requires hideCloseButton to be false (default). Also clears the user's saved editing session. |
None |
Analytics
The Studio Widget includes built-in usage analytics, handled by Cloudinary. The widget sends events automatically as soon as the widget renders and while users interact with it. Cloudinary uses this data to understand how the widget is used and to improve it.
These analytics are internal to Cloudinary, so they aren't available for you to view. No configuration is required, and you can't disable them or connect your own analytics tracker. To track how your users work with the widget, listen for the widget events in your application.
Error
Rate this page:
