Upload Widget API reference

The upload widget API reference details all the parameter options that you can use when configuring the upload widget.

Tips

Initialization methods

The Initialization JavaScript methods are publicly available after including Cloudinary's upload widget JavaScript file.

Copy to clipboard
<script src="https://widget.cloudinary.com/v2.0/global/all.js" type="text/javascript">
</script>

The all.js file instantiates the cloudinary class with access to the following methods:

Note
For the list of methods that can be used with the returned widget object from one of these initialization methods, see the instance methods.


setCloudName

Globally sets the cloud name for all widget method calls.

Syntax

cloudinary.setCloudName(name)

Parameter Type Description
name String The Cloudinary cloud name.

Example

Copy to clipboard
cloudinary.setCloudName("my-cloud");

createUploadWidget

Creates a widget object and frame in memory, but does not display it until the open() method of the returned widget object is called.

Tip
Improve the perceived performance of your site by creating the widget while your site is loading and then calling the open() method from a click event.

Syntax

cloudinary.createUploadWidget(options, resultCallback)

Parameter Type Description
options Map A map of the upload widget parameters to apply. See the parameters section for a full list of options available.
resultCallback Function An optional function called for event handling. The callback method has the following signature function(error, result) where error is either null if successful or an error message if there was a failure, while result is a JSON object detailing the triggered event.

Example

Copy to clipboard
var widget = cloudinary.createUploadWidget({ 
  cloudName: "demo", uploadPreset: "preset1" }, (error, result) => { });
widget.open();

openUploadWidget

Creates a widget object and frame in memory, and also opens the widget.

Syntax

cloudinary.openUploadWidget(options, resultCallback)

Parameter Type Description
options Map A map of the upload widget parameters to apply. See the parameters section for a full list of options available.
resultCallback Function An optional function called for event handling. The callback method has the following signature function(error, result) where error is either null if successful or an error message if there was a failure, while result is a JSON object detailing the triggered event.

Example

Copy to clipboard
cloudinary.openUploadWidget({
  cloudName: "demo", uploadPreset: "preset1" }, (error, result) => { });

applyUploadWidget

Creates a widget object and frame in memory, and also modifies a given element to a blue button (customizable look & feel) that, when clicked, opens a pre-created upload widget. In addition, the form and thumbnails options are implicitly set by default to the containing form of the given element.

Syntax

cloudinary.applyUploadWidget(element, options, resultCallback)

Parameter Type Description
element Element The containing element on the page to be modified to a button.
options Map A map of the upload widget parameters to apply. See the parameters section for a full list of options available.
resultCallback Function An optional function called for event handling. The callback method has the following signature function(error, result) where error is either null if successful or an error message if there was a failure, while result is a JSON object detailing the triggered event.

Example

Copy to clipboard
cloudinary.applyUploadWidget(document.getElementById('opener'), 
  { cloudName: "demo", uploadPreset: "preset1" }, (error, result) => { });

cloudinary_upload_widget

Note
For use with jQuery - supported only for backward compatibility with upload widget 1.x

Same as applyUploadWidget. Uses a jQuery selector to apply the widget on matching elements.

Example

Copy to clipboard
$('#opener2').cloudinary_upload_widget({ cloudName: "demo", uploadPreset: "preset1" });

Parameters

Important

Besides for the required parameters, only include other parameters in order to override their default values.

The following tables list all available parameters (options) for creating and initializing an upload widget with one of the Initialization methods method:

Note
The standard camelCase option names are shown here.
For backward compatibility with upload widget 1.x, snake_case is also supported.

Required parameters

The following parameters are required when initializing the upload widget:

Parameter Type Description
cloudName String Your Cloudinary account cloud name. Can be set either globally using setCloudName or explicitly for each widget creation call.
Example: demo
uploadPreset String
(optional if uploadSignature is used)
The name of an upload preset defined for your Cloudinary account. If using the upload widget for unsigned uploads, make sure you specify an unsigned upload preset, and conversely, if you choose to provide an upload preset for a widget performing signed uploads, make sure you provide a signed upload preset. You can define upload presets either on the Upload tab of the console settings or by using the Admin API.
Example: preset1

Widget parameters

Parameter Type Description
sources Array of Strings List of sources that should be added as tabs (web) or source options (mobile/responsive) in the widget. Possible values: local, url, camera, dropbox, image_search, facebook, instagram, shutterstock, google_drive
Notes:
- The sources are displayed in the same order that you add them to this parameter.
- camera is not relevant for mobile devices (the local option also allows capturing from the camera on mobile devices) and is currently supported in all modern browsers (not supported in Internet Explorer or Desktop Safari).
- The camera and dropbox source options will appear only if the upload widget is embedded in an HTTPS page.
secure Boolean Whether the widget uses the HTTPS protocol instead of HTTP.
Default: true.
encryption Map of key-iv pairs The encryption key and initialization vector to use for encrypting uploaded files.
Example:{ key: "ff234fe526725753fa45b53325", iv: "cd8a46d72e26a365dca78ef" }
defaultSource String The source that's selected when the widget is opened.
Default: local
multiple Boolean Whether selecting and uploading multiple images is allowed. Completion callback is called only when all images complete uploading. If set to true, multiple hidden fields of image identifiers are created. If set to false, only a single image is allowed in any source.
Default: true
maxFiles Integer The maximum number of files allowed in multiple upload mode. If a user selects or drags more than the allowed amount, no files will be uploaded.
Default: unlimited
Example: 10

Cropping parameters

Parameter Type Description
cropping Boolean Set to true if you want to allow your users to interactively crop their images before uploading them to Cloudinary. Interactive cropping allows users to mark the interesting part of images, and the selected dimensions are sent as the customCoordinates or faceCoordinates upload parameter, depending on the value used for croppingCoordinatesMode.
Setting gravity to custom or faces (as appropriate) when generating delivery URLs will deliver the image with the cropping that the user defined in the widget. Incoming cropping can be applied before saving the image by including the crop mode set to custom gravity in your upload preset.
Cropping is supported only with single-file uploading so make sure to also set the multiple widget parameter to false in order to enable interactive cropping. Default: false
showSkipCropButton Boolean Whether to display the 'skip' button on the interactive cropping step, making the step mandatory if set to false.
Relevant only if the cropping feature is enabled.
Default: true
croppingAspectRatio Decimal If specified, enforce the given aspect ratio on the selected region when performing interactive cropping. The aspect ratio is defined as width/height. For example, 0.5 for a portrait oriented rectangle or 1 for square.
Relevant only if the cropping feature is enabled.
Note: If the user tries to upload an asset with the exact same aspect ratio, the 'crop' button will start off disabled. The user will either have to click the 'skip' button, or slightly modify the cropping region to enable the 'crop' button.
Default: null
Example: 0.5
croppingDefaultSelectionRatio Decimal Initialize the size of the cropping selection box to a different value from the default. The value is calculated as a proportion of the image's size.
Relevant only if the cropping feature is enabled.
Default: 1.0. Range: 0.1 to 1.0.
Example: 0.75
croppingShowDimensions Boolean Whether to display the cropping dimensions in the top left corner of the cropping region.
Relevant only if the cropping feature is enabled.
Default: false.
croppingCoordinatesMode String: custom or face Determines how to apply the selected region coordinates:
custom - the selected region is set as the customCoordinates upload parameter (default).
face - the selected region is set as the faceCoordinates upload parameter.
Relevant only if the cropping feature is enabled.
croppingShowBackButton Boolean Whether to show a Back button when in cropping mode.
Relevant only if the cropping feature is enabled.
Default: true

Sources parameters

See the Third-party upload sources section for more details on working with the various sources.

Parameter Type Description
Dropbox:
dropboxAppKey String Your DrooBox App key. Required if adding the dropbox source.
Facebook:
facebookAppId String The App ID of your own Facebook application. Defaults to using the Cloudinary Media Upload app to access their Facebook accounts if not provided.
Image search:
googleApiKey String Your API key needed to access Google APIs. Required if adding the image_search source.
searchBySites Array of strings The URLs of sites to allow for Image Search. If more than one site is given, the Search by Site dropdown is added. To allow searching the entire web, use the value "all".
Default: all
searchByRights Boolean Set to true to add a dropdown box for your users to select a licensing filter when using the search.
Default: false
Instagram:
instagramClientId String The App ID of your own Instagram application for accessing your users Instagram accounts. Defaults to using the Cloudinary Media Upload app to access their Instagram accounts if not provided.
Google Drive:
googleDriveClientId String The Client ID of your own Google Drive application for accessing your users Google Drive accounts. Defaults to using the Cloudinary Google Drive app to access their accounts if not provided.

Upload parameters

Parameter Type Description
publicId String Custom public ID to assign to a single uploaded image. If not specified, either a randomly generated string or the original file name is used as the public ID according to the unsigned upload preset. To ensure secure usage, overwriting previously uploaded images sharing the same public ID is not supported (unless you also include "overwrite = true" in the upload preset).
Default: null.
Example: profile_11002
folder String Folder name for all uploaded images. Acts as the prefix of assigned public IDs.
Default: null (uploads to the root folder).
Example: user_photos
tags Array of Strings One or more tags to assign to the uploaded images.
Default: null.
Example: ['users', 'content']
resourceType String Limits uploaded files to the specified type. By default, all resource types are allowed.
Possible values: auto, image, video, raw.
Default: auto.
context Map of key-value pairs Additional context metadata to attach to the uploaded resources.
Example:{ alt: "my_alt", caption: "my_caption"}
uploadSignature string or function Either a string representing the precalculated signature of all upload parameters used, or a function to generate the signature string dynamically. The function accepts 2 parameters, the first is a resultCallback (function) and the second is an object with the relevant upload parameters that are needed for generating the signature.
Example: c347053314777423cd4f
For details, see Generating authentication signatures.
uploadSignatureTimestamp Number The Unix time in seconds of the current time. The timestamp is valid for 1 hour.
Relevant only if uploadSignature is also provided.
Example: 1315060076

Client-side parameters

Parameter Type Description
clientAllowedFormats Array of file formats Allows client-side validation of the uploaded files based on their file extensions. You can specify one or more file extensions.
Default: null.
Example: ["png","gif", "jpeg"]
maxFileSize Integer. Number of bytes. If specified, perform client-side validation to prevent uploading files larger than the given bytes size.
Default: null (no client-side limit)
Example: 5500000 (5.5 MB)
Notes:
- Applies to local files only
- Upload size is limited on the server-side by the maximum file size set in your account's Usage Limits
- The preview, crop, and pixel-count options are not available for files larger than 40 MB (the files can still be uploaded)
maxImageFileSize Integer. Number of bytes. If specified, perform client-side validation to prevent uploading image files larger than the given bytes size.
Default: null (no client-side limit)
Example: 1500000 (1.5 MB)
Notes:
- Overrides maxFileSize (if set) for images
- Applies to local files only
- Upload size is limited on the server-side by the maximum file size set in your account's Usage Limits
- The preview, crop, and pixel-count options are not available for files larger than 40 MB (the files can still be uploaded)
maxVideoFileSize Integer. Number of bytes. If specified, perform client-side validation to prevent uploading video files larger than the given bytes size.
Default: null (no client-side limit)
Example: 15000000 (15 MB)
Notes:
- Overrides maxFileSize (if set) for videos
- Applies to local files only
- Upload size is limited on the server-side by the maximum file size set in your account's Usage Limits
maxRawFileSize Integer. Number of bytes. If specified, perform client-side validation to prevent uploading raw files larger than the given bytes size.
Default: null (no client-side limit)
Example: 2000000 (2 MB)
Notes:
- Overrides maxFileSize (if set) for raw files
- Applies to local files only
- Upload size is limited on the server-side by the maximum file size set in your account's Usage Limits
maxImageWidth Integer. Number of pixels. If specified, client-side scale-down resizing takes place before uploading if the width of the selected file is larger than the specified value.
Alternatively, can be used in conjunction with validateMaxWidthHeight to prevent uploading of images that exceed this value.
Default: null (no resizing)
Example: 2000
maxImageHeight Integer. Number of pixels. If specified, client-side scale-down resizing takes place before uploading if the height of the selected file is larger than the specified value.
Alternatively, can be used in conjunction with validateMaxWidthHeight to prevent uploading of images that exceed this value.
Default: null (no resizing)
Example: 2000
validateMaxWidthHeight Boolean If specified, client-side validation takes place before uploading. If the width and/or height of the image is larger than maxImageWidth and/or maxImageHeight respectively, the upload is cancelled and no client-side scale-down resizing takes place.
Default: false (no validation)
minImageWidth Integer. Number of pixels. If specified, client-side validation takes place before uploading. If the width of the selected file is smaller than the specified value, the upload is cancelled.
Default: null (no validation)
Example: 200
minImageHeight Integer. Number of pixels. If specified, client-side validation takes place before uploading. If the height of the selected file is smaller than the specified value, the upload is cancelled.
Default: null (no validation)
Example: 200
croppingValidateDimensions Boolean Relevant only if the cropping feature is enabled AND one or more of the following parameters are also set: maxImageWidth, maxImageHeight, minImageWidth or minImageHeight.
If specified, the client-side validation takes place both on the size of the original image and on the size of the cropping region marked by the user.
Default: false.
maxChunkSize Integer. Number of bytes. Configure the maximum chunk size for uploading large files. The value must be at least 5 MB (5000000).
Default: 20000000

Containing page parameters

Parameter Type Description
form CSS selector The selector (CSS path) of the form, to which you would like to append hidden fields with the identifiers of the uploaded images.
Implicitly set by default to the containing form of the given element when the widget is created using applyUploadWidget or $.fn.cloudinary_upload_widget.
Default: null
Example: #my_form
fieldName Form field name The name of the hidden field added to your form when uploading is completed. Multiple hidden fields with the same name are created for multiple uploaded assets. The name can include [] for supporting web frameworks such as Ruby on Rails.
Default: image
Example: photo[]
thumbnails CSS selector The selector (CSS path) of an HTML element that acts as the container for appending upload thumbnails.
Implicitly appended by default to the containing element (if it exists) of the upload widget element.
If you don't want to display thumbnails at all, set to 'false'.
Default: null
Example: .content .uploaded
thumbnailTransformation String or Array of maps The Cloudinary transformation (manipulation) to apply on uploaded assets for embedding thumbnails in your site. Any resizing, cropping, effects, and other Cloudinary image transformation options can be applied by specifying a transformation string or an array of mapped transformations.
Thumbnail transformations can be eagerly generated during upload by defining a set of eager transformations in your defined upload preset.
Default: [{ width: 90, height: 60, crop: 'limit' }]
Examples:
[{ width: 100, height: 100, crop: 'fit' }]
[ {width: 200, height: 200, crop: 'fill'}, {effect: 'sepia'} ]
"w_200,h_200,c_fill"

Customization parameters

Parameter Type Description
buttonClass String Enables you to override the default CSS class name of the upload button added to your site. The default CSS style is applied to the cloudinary-button class, which you can override using CSS directives. Alternatively, you can specify any class name that matches your website design.
Default: cloudinary-button
buttonCaption String Enables you to override the default caption of the upload button added to your site.
Default: Upload image
theme String The name of a predefined widget theme. Widget behavior is the same for all themes.
Supported themes: default, white, minimal, purple.
Default: default
styles Object Advanced customization of the widget's look & feel. Enables you to override the widget's default colors, fonts, icons and other elements by providing a custom style definition. See the Look and feel customization sample as a reference implementation. Default: the widget's default settings are used for all elements that are not specifically overridden
text Object "key":"value" pairs of text to override the widget's default text labels. See the Localization sample as a reference implementation.

Advanced parameters

Parameter Type Description
showPoweredBy Boolean Whether the Powered By Cloudinary icon is displayed.
Default: true.
Note: Supported only for paid Cloudinary accounts and requires some time for cache expiration.
autoMinimize Boolean Automatically minimize the widget after the upload begins.
Default: false
getTags Function A function that is called for adding tagging suggestions whenever the text changes in the Add a Tag Advanced text field.
getUploadPresets Function A function that is called for populating an upload preset selection field added to the Advanced options.
preBatch Function A function that performs pre-batch validation before the upload starts.
prepareUploadParams Function A function for preparing upload parameters before the upload starts.
language String Determines which of the text parameter languages to use for the widget.
Default: en
showAdvancedOptions Boolean Whether to display the Advanced options, which enables users to set the Public ID, Add a Tag, and select an Upload Preset (only if getUploadPresets is defined).
Default false
showCompletedButton Boolean Whether the Completed button will be displayed after the upload completes. When a user clicks the button, the widget fires the show-completed event.
Default false
showUploadMoreButton Boolean Whether the Upload More button will be displayed after the upload completes.
Default: true
singleUploadAutoClose Boolean Whether the upload widget automatically closes after the upload completes.
Default: true
queueViewPosition String The display position of the minimized upload queue expressed as an offset value from either the right or left edge, followed by a colon and then the offset value in CSS units from that edge.
Default right:35px
showInsecurePreview Boolean Whether the widget displays a preview of assets from HTTP (non-secure) URLs selected for uploading. Assets from HTTPS URLs will display a preview regardless of this parameter's value.
Default false
inlineContainer String selector or DOM element Enables embedding the widget inside your web page instead of it appearing as a modal dialog.
Default: null
Examples:
#my-widget-container
document.getElementById('my-widget-container');

Instance methods

The following methods can be used with the widget object that is returned by one of the Initialization methods:


open

Renders an existing widget currently in memory, but that is not currently displayed.

Syntax

open(files)

Parameter Type Description
files URL An optional URL, in which case the widget either skips directly to uploading the given asset, or skips the source selection options and opens the widget with the given asset ready for cropping (if that option is enabled).

Example

Copy to clipboard
var widget = cloudinary.createUploadWidget({ 
  cloudName: "demo", uploadPreset: "preset1", cropping: true}, (error, result) => { });
widget.open({files: ["https://my.example.come/my_example_image.jpg"]});

close

Closes the widget and removes it from memory.

Syntax

close(quiet)

Parameter Type Description
quiet Boolean When true, skips the confirmation box if the widget is closed while still uploading assets.

Example

Copy to clipboard
var widget = cloudinary.createUploadWidget({ 
  cloudName: "demo", uploadPreset: "preset1"}, (error, result) => { });
widget.close({quiet: true});

update

Updates a widget currently in memory with new options.

Syntax

update(options)

Parameter Type Description
options Map A map of the upload widget parameters to apply. See the parameters section for a full list of options available.

Note
The following parameters are NOT supported by update: secure, uploadSignature, getTags, preBatch, inlineContainer, and fieldName.

Example

Copy to clipboard
var widget = cloudinary.createUploadWidget({ 
  cloudName: "demo", uploadPreset: "preset1"}, (error, result) => { });
widget.update({uploadPreset: "1n3gh62"});

hide

Hides a previously rendered widget without removing it from memory.

Syntax

hide()

Example

Copy to clipboard
widget.hide();

show

Renders a previously hidden widget.

Syntax

show()

Example

Copy to clipboard
widget.show();

minimize

Minimizes the widget.

Syntax

minimize()

Example

Copy to clipboard
widget.minimize();

isShowing

Returns whether the widget is currently visible.

Syntax

isShowing()

Example

Copy to clipboard
if (widget.isShowing()){ 
  // my code here 
};

isMinimized

Returns whether the widget is currently minimized.

Syntax

isMinimized()

Example

Copy to clipboard
if (widget.isMinimized()){
  // my code here 
};

Events

Tip
See widget events in the upload widget guide for more information on working with events.

The following list details every event fired as well as the corresponding information passed to the result object:

abort

The user aborted upload.

Copy to clipboard
result = {
    event: "abort",
    info: {
      ids: [],
      all: true | false   //whether abort-all was clicked
}};

batch-cancelled

The uploading was cancelled.

Copy to clipboard
result = {
    event: "batch-cancelled",
    info: { reason: "MAX_EXCEEDED" | "INVALID_PUBLIC_ID" }
};

close

The user closed the upload widget.

Copy to clipboard
result = {
    event: "close"
};

display-changed

The display has changed.

Copy to clipboard
result = {
    event: "display-changed",
    info: "shown" | "hidden" | "minimized" | "expanded"  
};

publicid

The contents of the public id input field (Advanced options) changed.

Copy to clipboard
result = {
    event: "publicid",
    info: { id: "my-public-id" }
};

queues-end

All files have finished uploading.

Copy to clipboard
result = {
    event: "queues-end",
    info: {} // information about all files processed by the api
};

queues-start

The files are about to begin uploading.

Copy to clipboard
result = {
    event: "queues-start"
};

retry

The user retried after failed uploads.

Copy to clipboard
result = {
    event: "retry",
    info: {
      ids: [],
      all: true | false   //whether retry-all was clicked
}};

show-completed

The user clicked the show completed button (requires 'showCompletedButton = true' widget option).

Copy to clipboard
result = {
    event: "show-completed",
    info: {
      items: [{id, name, size, type, status, done, progress, file: {}, uploadInfo: {} 
           // uploadInfo is the information returned from the upload response
    }, {...}] 
}};

source-changed

The user selected a different source.

Copy to clipboard
result = {
event: "source-changed",
info: { source: "local" | "url" | "facebook"   //etc.   
}};

success

The upload was successful.

Copy to clipboard
result = {
    event: "success",
    info: {}  // information returned from the upload api method
};

tags

The contents of the tags input field (Advanced options) changed.

Copy to clipboard
result = {
    event: "tags",
    info: {
      tags: ["dog", "family", "home"] }   //tags currently in the field
};

upload-added

A file was selected for upload.

Copy to clipboard
result = {
    event: "upload-added",
    info: {
      file: { lastModified, lastModifiedDate, name, size, type },
      publicId: "public-id" }
};

✔️ Feedback sent!

Rate this page: