Studio widget API reference

The Studio widget API reference details the options, methods, and events that you can use when embedding the Studio widget in your web application.

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.14/all.js.

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.
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.
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.
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 with the delivery URL.
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, including applied transformations and selected assets, and restores it the next time it opens. 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.

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, 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.

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 closes the widget.	None

Analytics

The Studio widget includes built-in usage analytics, handled by Cloudinary. No configuration is required, and you can't disable it or connect your own analytics tracker.