> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload Widget API reference


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

The options in this reference relate to the latest [version](upload_widget_changelog) of the Cloudinary Upload widget.

> **See also:**:
>
> * For in-depth information, see the [Upload widget](upload_widget) guide.

> * Use the [Upload widget demo](https://demo.cloudinary.com/uw/) to try out some of the widget options.

> * Check out one of our code explorers to play with an Upload widget implementation: [JavaScript](https://stackblitz.com/edit/github-vt6fzc-wms1nc) | [React](https://stackblitz.com/edit/cloudinary-upload-widget-react) | [Angular](https://codesandbox.io/s/upload-widget-angular-hp2rmc) | [Vue](https://codesandbox.io/s/upload-widget-vue-hmezny)

## Initialization methods

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

```js
<script src="https://upload-widget.cloudinary.com/latest/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](#instance_methods).

---

### createUploadWidget

Creates a widget object and frame in memory, but does not display it until the [open()](#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](#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](#events).

#### Example

```js   
var widget = cloudinary.createUploadWidget({ 
  cloudName: "my-cloud-name", 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](#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](#events).

#### Example

```js 
cloudinary.openUploadWidget({
  cloudName: "my-cloud-name", 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](#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](#events).

#### Example

```js  
cloudinary.applyUploadWidget(document.getElementById('opener'), 
  { cloudName: "my-cloud-name", 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

```js       
$('#opener2').cloudinary_upload_widget({ cloudName: "my-cloud-name", uploadPreset: "preset1" });
```

---

### setCloudName

Globally sets the cloud name for all widget method calls.

#### Syntax 

`cloudinary.setCloudName(name)`

Parameter | Type | Description
---|---|---
name | String | The product environment cloud name.

#### Example

```js
cloudinary.setCloudName("my-cloud");
```

## Parameters

> **INFO**: 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](#initialization_methods) method:

* [Required parameters](#required_parameters)
* [Widget parameters](#widget_parameters)
* [Cropping parameters](#cropping_parameters)
* [Sources parameters](#sources_parameters)
* [Upload parameters](#upload_parameters)
* [Client-side parameters](#client_side_parameters)
* [Containing page parameters](#containing_page_parameters)
* [Customization parameters](#customization_parameters)
* [Advanced parameters](#advanced_parameters)

> **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 product environment 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 product environment. 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** page of the Console Settings or by using the Admin API. Example: `preset1`

### Widget parameters

Parameter | Type | Description
---|---|--- 
sources  | Array of Strings  | List of [sources](upload_widget#third_party_upload_sources) that should be added as tabs (web) or source options (mobile/responsive) in the widget. Possible values: `local`, `url`, `camera`, `dropbox`, `image_search`, `shutterstock`, `gettyimages`, `istock`, `unsplash`, `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](upload_widget#encryption) 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 assets is allowed. Completion callback is called only when all assets complete uploading. If set to true, multiple hidden fields of asset identifiers are created. If set to false, only a single asset is allowed in any source. *See note below*.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. *See note below*. Default: *unlimited* Example: `10`

> **NOTE**: Cloudinary recommends setting a limit for `maxFiles`. Although the widget does not limit the number of uploads from the front end side, there is a limit of 20 simultaneous calls on the backend side.

### 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. **Note**: This step is skipped if the user uploads a video or an image format that is not supported by browsers (e.g., PSD or SVG files).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.**Note**: In some cases, the button will still be shown regardless of this setting (e.g. if croppingAspectRatio is set to 1.0 and the user tries to upload an image already with an aspect ratio of 1.0) 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](upload_widget#third_party_upload_sources) section for more details on working with the various sources.

Parameter | Type | Description
---|---|--- 
`Dropbox:`||
dropboxAppKey | String | Your DropBox App key. Required if adding the `dropbox` source.
`Image search:`||
googleApiKey | String | Your API key needed to access [Google APIs](https://developers.google.com/custom-search/). 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** drop-down is added. To allow searching the entire web, use the value "all".Default: `all`
searchByRights | Boolean | Set to `true` to add a drop-down box for your users to select a licensing filter when using the search.Default: `false`
`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 asset. 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 assets sharing the same public ID is not supported (unless you also include "overwrite = true" in the upload preset).Default: `null`  Example: `profile_11002`
asset\_folder | String |  The folder where the uploaded assets are placed within the Cloudinary repository. This value doesn't impact the asset’s public ID path.Default: `null` (uploads to root folder, even if the public ID value includes slashes)Example: `user_photos`**Not relevant for product environments using the legacy fixed folder mode.**
folder |String|  **Only relevant for product environments using the legacy fixed folder mode.** The full path of the folder where the uploaded assets are placed and also a path value that's prepended to all `public_id` values with a forward slash. Default: `null` (uploads to root folder)Example: `user_photos`**Note**: If [Dynamic folders](folder_modes) mode is enabled on your product environment, this parameter is deprecated, and it's recommended to use the `asset_folder` parameter to control where the asset will be placed.
useAssetFolderAsPublicIdPrefix | Boolean | Whether to use the given folder as a prefix for all public IDs. Default: `false`
publicIdPrefix | String | The string to add as a prefix for all public IDs. 
tags |Array of Strings| One or more tags to assign to the uploaded assets. 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 contextual metadata to attach to the uploaded resources. Example:`{ alt: "my_alt", caption: "my_caption"}`
detection | String | Invokes the relevant add-on. Set to:\_\[\<version\>\] (e.g. `coco_v2`) to detect content using the [Cloudinary AI Content Analysis](cloudinary_ai_content_analysis_addon#automatic_image_tagging) add-on.`adv_face` to detect facial attributes using the [Advanced Facial Attribute Detection](advanced_facial_attributes_detection_addon) add-on.`aws_rek_face` to detect celebrities and facial attributes using the [Amazon Rekognition Celebrity Detection](aws_rekognition_celebrity_and_face_detection_addon) add-on.
onSuccess | String |  Allows you to update an asset by specifying custom logic with JavaScript that is executed after the upload to Cloudinary is completed successfully. This can be useful for conditionally adding tags, contextual metadata, and structured metadata, depending on the results of using the `detection` parameter on upload. For more details see [On Success update script](upload_parameters#on_success_update_metadata_after_upload).
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](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 Strings| Allows client-side validation of the uploaded files based on their file extensions. You can specify one or more file extensions, and/or limit the allowed files to "video" or "image". Only applies when uploading files from a local device.**Note**: As a shortcut, you can use a string to pass a single value (e.g. "gif")Default: `null`. Example: `["webp", "gif", "video"]`
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.**Note**: Only relevant when uploading local files, and not files from a URL.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.**Note**: Only relevant when uploading local files, and not files from a URL.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. **Note**: Only relevant when uploading local files, and not files from a URL.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. **Note**: Only relevant when uploading local files, and not files from a URL.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 assets. 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](upload_widget#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](upload_widget#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](upload_widget#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](upload_widget#upload_preset_selection) field added to the **Advanced** options. 
preBatch | Function | A function that performs [pre-batch validation](upload_widget#pre_batch_validation) before the upload starts. 
prepareUploadParams | Function | A function for [preparing upload parameters](upload_widget#prepare_upload_parameters) before the upload starts. The prepareUploadParams callback only supports preparing the following parameters:  `apiKey`, `auditContext`, `context`, `folder`, `invalidate`, `metadata`, `overwrite`, `publicId`, `qualityAnalysis`, `resourceType`, `signature`, `tags`, `uniqueFilename`, `uploadPreset` `uploadSignatureTimestamp`, `useFilename`.
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](#initilization_methods):

---

### open

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

#### Syntax 

`open(source, options)`

Parameter | Type | Description
---|---|---
source | String | The source (tab) the widget should open on. **Default**: null
options | Map | Any optional values to pass. Currently supports:- `files`: (Array of strings) Optional asset URLs, in which case the widget either skips directly to uploading the given assets, or skips the source selection options and opens the widget with the given assets ready for cropping (if that option is enabled). 

#### Example

```js   
var widget = cloudinary.createUploadWidget({ 
  cloudName: "my-cloud-name", uploadPreset: "preset1", cropping: true}, (error, result) => { });
widget.open(null, {files: ["https://my.example.come/my_example_image.jpg"]});
```

---

### close
Closes and resets the widget to its initial state without removing it from memory.

**See also**: [destroy](#destroy) | [hide](#hide)

#### Syntax 

`close(options)`

Parameter | Type | Description
---|---|---
options | Map | Any optional values to pass. Currently supports:- `quiet`: (boolean) When true, skips the confirmation box if the widget is closed while still uploading assets. **Default**: false.

#### Example

```js   
var widget = cloudinary.createUploadWidget({ 
  cloudName: "my-cloud-name", 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](#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

```js   
var widget = cloudinary.createUploadWidget({ 
  cloudName: "my-cloud-name", uploadPreset: "preset1"}, (error, result) => { });
widget.update({uploadPreset: "1n3gh62"});
```

---

### hide
Hides a previously rendered widget while retaining its current state in memory.

**See also**: [close](#close_method) | [destroy](#destroy) 

#### Syntax 

`hide()`

#### Example

```js   
widget.hide();
```

---

### show

Renders a previously hidden widget.

#### Syntax 

`show()`

#### Example

```js   
widget.show();
```

---

### minimize

Minimizes the widget.

#### Syntax 

`minimize()`

#### Example

```js   
widget.minimize();
```

---
### destroy

Closes the widget and completely removes it from the DOM and memory, freeing up resources. This method returns a promise that is resolved when the cleanup process is finished. 

**See also**: [close](#close_method) | [hide](#hide) 

#### Syntax 

`destroy(options)`

Parameter | Type | Description
---|---|---
options | Map | Any optional values to pass. Currently supports:- `removeThumbnails` (Boolean) When true, also removes any [thumbnails](#thumbnails) that were displayed after upload. **Default**: false.

#### Example

```js   
const widget = cloudinary.createUploadWidget({
   cloudName: "my-cloud-name", uploadPreset: "preset1"}, (error, result) => { });
   // widget...
});
widget.destroy({ removeThumbnails: true })
   .then(() => {
      console.log("Widget was destroyed");
    });
```

---

### isShowing

Returns whether the widget is currently visible.

#### Syntax 

`isShowing()`

#### Example

```js   
if (widget.isShowing()){ 
  // my code here 
};
```

---

### isMinimized

Returns whether the widget is currently minimized.

#### Syntax 

`isMinimized()`

#### Example

```js   
if (widget.isMinimized()){
  // my code here 
};
```

---

### isDestroyed

Returns whether the [destroy](#destroy) method was called on this instance.

#### Syntax 

`isDestroyed()`

#### Example

```js   
if (widget.isDestroyed()){
  // my code here 
};
```

## Events

> **TIP**: See [widget events](upload_widget#api_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.

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

### batch-cancelled

The uploading was cancelled.

```js
result = {
    event: "batch-cancelled",
    info: { reason: "MAX_EXCEEDED" | "INVALID_PUBLIC_ID" }
};
```

### close
The user closed the Upload widget.

```js
result = {
    event: "close"
};
```

### display-changed

The display has changed.

```js
result = {
    event: "display-changed",
    info: "shown" | "hidden" | "minimized" | "expanded"  
};
```

### publicid

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

```js
result = {
    event: "publicid",
    info: { id: "my-public-id" }
};
```

### queues-end

All files have finished uploading.

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

### queues-start

The files are about to begin uploading.

```js
result = {
    event: "queues-start"
};
```

### retry

The user retried after failed uploads.

```js
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).

```js
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.

```js
result = {
event: "source-changed",
info: { source: "local" | "url"  // etc.   
}};
```

### success

The upload was successful.

```js
result = {
    event: "success",
    info: {}  // information returned from the upload api method
};
```

### tags

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

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

### upload-added

A file was selected for upload.

```js
result = {
    event: "upload-added",
    info: {
      file: { lastModified, lastModifiedDate, name, size, type },
      publicId: "public-id" }  // the value currently in the public ID input field
};
```