Upload widget

Cloudinary's upload widget is a complete, interactive user interface that enables your users to upload files from a variety of sources to your website or application. The widget, requiring just a couple lines of code to integrate, eliminates the need to develop in-house interactive media upload capabilities.

Note
For information on the previous version of the upload widget, see the Upload widget v1.x documentation. Note that the previous version has been deprecated and support for that version will be withdrawn in the near future. See this KB Article for more information on migrating to the current version of the upload widget.

Upload widget main screen

The upload widget responsively resizes to fit in the available width, with the display functionality automatically adjusting on-the-fly for use in mobile applications.

Upload widget main screen

The widget offers uploading from a variety of sources: your local device, remote URL, the computer or mobile device camera, Google image search, and social media accounts including Dropbox, Instagram or Facebook. The widget supports drag & drop functionality, interactive cropping, upload progress indication, and thumbnail previews. The widget also monitors and handles uploading errors and offers extensive event handling for integrating your own code.

You can implement the widget for unsigned uploading directly from the browser to Cloudinary storage, without involving your servers in the process. The widget sends JavaScript callbacks on successful uploads, so you can integrate the upload process back into your existing media pipeline. You can addtionally configure Cloudinary to send server-side callbacks. Advanced users can also use the upload widget with signed uploads for a more secure process when required.

Once uploaded, images and videos can be resized, cropped and manipulated by Cloudinary on-the-fly so they can be embedded as needed in your website or mobile app.

The upload widget requires only pure JavaScript to integrate and is easy to use within any web development framework.

Quick example

To use Cloudinary's upload widget in your site with unsigned uploads, include the widget's remote JavaScript file (delivered optimized via a fast CDN) and then specify your Cloudinary account cloudName and an uploadPreset when calling the method to open the widget.

The following sample code binds to the click event of a link in a web page, and calls the cloudinary.openUploadWidget method to open the upload widget:

<a href="#" id="upload_widget_opener">Upload multiple images</a>

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

<script type="text/javascript">  
  var myUploadWidget;
  document.getElementById("upload_widget_opener").addEventListener("click", function() {
    myUploadWidget = cloudinary.openUploadWidget({ 
      cloudName: 'demo', uploadPreset: 'preset1'}, (error, result) => { });
  }, false);
</script>

You can try out a live example by clicking the button below:

The example above uses standard JavaScript code to open the widget and allows multiple image uploading.
The example below uploads to a specified folder and enables interactive cropping of a single uploaded image.

<script src="https://widget.cloudinary.com/v2.0/global/all.js" type="text/javascript"></script>  
<script type="text/javascript">  
  cloudinary.applyUploadWidget('#upload_widget_opener',{ 
    cloudName: 'demo', uploadPreset: 'preset1', 
    cropping: true, folder: 'widgetdocs' }, (error, result) => { });    
</script>

You can try out another live example by clicking the button below:

How to setup and integrate the upload widget into your site or app.

For most needs, you can set up the upload widget for unsigned uploads. Using unsigned uploads with your widget makes it quick and simple for you to provide a UI where users can upload content to your site.

Signed uploads require a bit more setup and coding, but provide a more secure upload process when required.

Unsigned uploads

Unsigned uploads are somewhat less secure than signed uploads. For example, it is possible for a customer to inspect your client-side HTML code to find your cloud name and preset, and use that information to upload unwanted files to your account. For this reason, unsigned uploads have some protective limitations. For example, existing assets cannot be overwritten. The options you set in the unsigned preset can also limit the size or type of files that users can upload to your account using that preset.

To setup and add an upload widget for unsigned uploads:

  1. Include the cloudinary widget JavaScript file in your web page:
    https://widget.cloudinary.com/v2.0/global/all.js

    For example:

    <script src="https://widget.cloudinary.com/v2.0/global/all.js" type="text/javascript">  
    </script>
  2. Optional. Set your cloud name globally. If you include multiple widgets in your web page, you can use the setCloudName method to instruct all widgets on the page to upload to your Cloudinary account. Alternatively, you can set the cloud name as a parameter of each widget creation call.

  3. Create an unsigned upload preset. In the Upload settings of the Cloudinary console, create a new, unsigned upload preset. This preset serves as a form of security override, allowing client-side unsigned uploads. You supply the preset name in your widget creation call.
    If you've never created an unsigned preset, you must first select to enable unsigned uploading. When you do this, an empty upload preset is automatically created for you. Alternatively, you can create an unsigned upload preset using the Admin API.
    You can optionally edit the preset to modify its name or apply any of the available upload options, such as applying incoming transformations to control the size or type of asset users can upload using your widget, or to automatically generate certain eager transformations on all uploaded assets. For details, see Upload Presets.

  4. Add your widget. Use one of the widget creation methods described below. When you call the method, you specify the uploadPreset that you created in the previous step, your cloudName (if you did not set it globally), and any additional widget options you want to apply.
    For example, in the demo example earlier on this page, the method call includes the cropping option, which enables users to define cropping coordinates, and the folder option, which uploads all images from the widget to a specified folder.

Signed uploads

Instead of providing an upload preset name, you initialize the widget for signed uploads with the public API key and an upload signature that is generated either when the page is loaded or when the upload request is submitted.

To setup and implement the upload widget for signed uploads:

  1. Follow steps 1-3 above.

  2. Optional. Create a signed upload preset. When you use the upload widget for signed uploads, an upload preset is not necessary. But you can optionally create a signed preset if you want to define incoming or eager transformations on the uploaded image. Define the preset as described in Upload Presets and supply the preset name in the uploadPreset option when you call the widget creation method.

  3. Select string or function as the upload_signature type and prepare the required code.

    • String:

      • Requires your page to connect to the web server on page load to generate the signature.
      • Requires that all parameters required for signing are known at page load time. If user-input will affect the parameters, for example, if you are using the widget's interactive cropping option, then you must use the function option.
      • The signature string you provide is valid for one hour from the timestamp used in the signature. If a user keeps the page open for a long time, the signature string may expire.

      For details on generating the signature string, see Generating authentication signatures.

    • Function:

      • Requires you to create a function to generate the signature.
      • The function runs when the upload request is submitted, therefore, the timestamp does not risk expiring if the user keeps the page open.
      • The function receives the final parameters of the upload, including any parameters impacted by user interaction.

        Sample function:
        The following is an example of a function that uses a server-side endpoint to generate the signature.

          <script type="text/javascript">
            var generateSignature = function(callback, params_to_sign){
              $.ajax({
               url     : https://www.my-domain.com/my_generate_signature",
               type    : "GET",
               dataType: "text",
               data    : { data: params_to_sign},
               complete: function() {console.log("complete")},
               success : function(signature, textStatus, xhr) { callback(signature); },
               error   : function(xhr, status, error) { console.log(xhr, status, error); }
              });
            }
          </script>
  4. Add your widget. Use one of the widget creation methods described below. When you call the method, you specify your account apiKey, your cloudName (if you did not set it globally), the uploadSignature string or function, the uploadSignatureTimestamp (for string signatures only), and any additional widget options you want to apply.
    For example, the following method creates the upload-widget and calls the signature function shown in the previous step.

<script type="text/javascript">  
  $('#upload_widget_opener').cloudinary_upload_widget({ 
    cloudName: cloudName, apiKey: api_key,
    cropping: true, uploadSignature: generateSignature}, (error, result) => { });
</script>

Upload widget methods

The following JavaScript methods are publicly available after including Cloudinary's upload widget JavaScript file. The file instantiates the cloudinary class with access to the following methods:

cloudinary.setCloudName(name)

Globally sets the cloud name for all widget method calls.

For example:

<script src="https://widget.cloudinary.com/v2.0/global/all.js" type="text/javascript">
</script>
<script>
  cloudinary.setCloudName("my-cloud");
</script>

cloudinary.createUploadWidget(options, resultCallback)

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.

  • options is a map of the upload widget options to apply. See the full list of options available below.
  • resultCallback is 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.

For example:

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

The following methods can be used with the returned widget object:

  • open - Accepts an optional asset 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). For example:

    var widget = cloudinary.createUploadWidget({ 
      cloudName: "demo", uploadPreset: "preset1", cropping: "server"}, (error, result) => { });
    widget.open("https://my.example.come/my_example_image.jpg");
  • close - Accepts a single optional boolean parameter: quiet. When true, skips the confirmation box if the widget is closed while still uploading assets. For example:

    var widget = cloudinary.createUploadWidget({ 
      cloudName: "demo", uploadPreset: "preset1"}, (error, result) => { });
    widget.close({quiet: true});
  • update - Accepts a map of upload widget options to update the widget. Note that the following parameters are NOT supported by update: secure, uploadSignature, prepareUploadParams, getTags, preBatch, inlineContainer, and fieldName. For example:

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

cloudinary.openUploadWidget(options, resultCallback)

Same as createUploadWidget except that this method also opens the widget.

For example:

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

cloudinary.applyUploadWidget(element, options, result_callback)

Same as createUploadWidget except that it modifies the 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.

For example:

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

$.fn.cloudinary_upload_widget

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

For example:

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

Third-party upload sources

In addition to the 'My Files', 'Web Address', and 'Camera' sources, the upload widget supports a variety of third-party upload sources from which your users can upload images and videos. The sources are presented on multiple tabs (web) or options (mobile/responsive) for your users, so they can select the relevant source, browse through their files and select the ones they want to upload.

Upload widget sources

The sources parameter

The sources parameter accepts an array of string values defining the source options to add to the upload widget, where each source defines a new upload tab or source option within the widget. The sources parameter can be included in the method used for creating the upload widget, and is only specified when you want to limit the available sources (all are added by default if this parameter is omitted). The possible values for the sources parameter are as follows:

Value Description
local Upload a file from your local device. Adds the My Files source option.
url Upload a file from a remote location. Adds the Web Address source option.
camera Upload an image file via the device's camera. Adds the Camera source option. Note: Desktop/laptop only - a mobile device's camera is accessed through the local (My Files) source option.
dropbox Upload a file from your Dropbox account. Adds the Dropbox source option.
imageSearch Upload an image from the web using Google's Search Engine. Adds the Image Search source option.
facebook Upload an image from a Facebook account. Adds the Facebook source option.
instagram Upload an image from an Instagram account. Adds the Instagram source option.

Image Search source

The imageSearch option allows your users to select images from the web using your Google Custom Search account, and then upload them to your Cloudinary account. The search can be optionally confined to specific sites (e.g., your own website) and can be filtered by specified licensing criteria.

Image Search option

Important
To enable this search option, you must obtain an API Key from Google. The API Key is free to use within certain search rate limits, and there are various large scale commercial options as well. To enable Google Custom Search and generate your API Key see https://developers.google.com/custom-search/json-api/v1/overview.

To enable the Image Search option, add the following parameters to the method you use for creating the upload widget:

  • sources (Array of strings) - Optional. If you add this parameter to limit the available options, make sure to include the imageSearch option.
  • googleApiKey (String) - The API key for your Google Custom Search account.
  • searchBySites (Array of Strings) - Optional. The domain names of sites you want to allow for the search. If more than one site is specified then a Search by Site dropdown will be added, so your users can select the site to search. To allow searching the entire web, use the value all. Default value: all
  • searchByRights (Boolean) - Optional. Set to true to add a dropdown box so that users can select a licensing filter to apply to the image search. Default value: false.

Basic example:

cloudinary.openUploadWidget({
  cloudName: "demo", uploadPreset: "preset1",
  sources: [ 'local', 'url', 'imageSearch'],
  googleApiKey: 'AIrFcR8hKiRo' }, (error, result) => { });

Example with sites filter and rights filter:

cloudinary.openUploadWidget({
  cloudName: "demo", uploadPreset: "preset1",
  sources: [ 'local', 'url', 'imageSearch'],
  googleApiKey: 'AIrFcR8hKiRo',
  searchBySites: ["all", "cloudinary.com"],
  searchByRights: true }, (error, result) => { });

Image Search select

Dropbox source

The dropbox option allows your users to login to their own Dropbox account, browse through their folders and files, and then select the files to upload to your Cloudinary account. This option requires that the upload widget is embedded in a secure (HTTPS) page because the user sign-in to Dropbox must be over a secure connection.

To enable this upload option for your users, you must obtain an App key from Dropbox:

  1. Create a new app on the Dropbox App Console: Click My apps, select the Dropbox API and Full Dropbox options, name your app, and click the Create app button.
  2. On the next page, set the following redirect URI for your Dropbox application: https://widget.cloudinary.com/global/auth/index.html
  3. Copy the auto-generated App key for your Dropbox app: this will be configured as the value of the dropboxAppKey parameter when including Dropbox as an upload source in the upload widget (see below).
  4. Your Dropbox app is initially created in Development status for testing purposes. You can enable additional users with the Enable additional users button, and when your app is ready to go live, you need to click on the Apply for Production status to enable all your users to upload via the Dropbox app.
  5. For more information on creating Dropbox apps, see their documentation and take note of their branding guidelines.

Dropbox source Dropbox login

To enable the Dropbox source, add the following parameters to the method you use for creating the upload widget:

  • sources (Array of strings) - Optional. If you add this parameter to limit the available options, make sure to include the dropbox option.
  • dropboxAppKey (String) - The App key to your Dropbox App.

For example:

cloudinary.openUploadWidget({
  cloudName: "demo", uploadPreset: "preset1",
  sources: [ 'local', 'url', 'dropbox'],
  dropboxAppKey: '1dsf42dl1i2' },  (error, result) => { });

Facebook source

The facebook option allows your users to login to their own Facebook account, browse through their photos (photos they have uploaded, photos they are tagged in, or albums they have created) and then select the images to upload to your Cloudinary account.

Facebook source Facebook login

To enable the Facebook source, add the following parameters to the method you use for creating the upload widget:

  • sources (Array of strings) - Optional. If you add this parameter to limit the available options, make sure to include the facebook option.
  • facebookAppId (String) - Optional. The App ID of your own Facebook application for accessing your users' Facebook accounts. If not proviced, uses the Cloudinary Media Upload app.

For example:

cloudinary.openUploadWidget({
  cloudName: "demo", uploadPreset: "preset1",
  sources: [ 'local', 'url', 'facebook'],
  facebookAppId: '2dds35jdw21' }, (error, result) => { });

Instagram source

The instagram option allows your users to login to their own Instagram account, browse through their photos, and then select the images to upload to your Cloudinary account.

Instagram source

To enable the Instagram source, add the following parameters to the method you use for creating the upload widget:

  • sources (Array of strings) - Optional. If you add this parameter to limit the available options, make sure to include the instagram option.
  • instagramClientId (String) - Optional. The App ID of your own Instagram application for accessing your users Instagram accounts. If not provided, uses the Cloudinary Media Upload app.

For example:

cloudinary.openUploadWidget({
  cloudName: "demo", uploadPreset: "preset1",
  sources: [ 'local', 'url', 'instagram'],
  instagramClientId" 'd7aadf962m' }, (error, result) => { });

API events

The upload widget methods include a callback function for implementing event handling. The callback 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.

Quick example for handling a successful upload:

cloudinary.openUploadWidget({
  cloudName: "demo", uploadPreset: "preset1"}, (error, result) => {
    if (result && result.event === "success") {
        // do something
    }
});

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

  • success - upload was successful

    result = {
        event: "success",
        info: {}  //information returned from upload api
    };
  • close - user closed the upload widget

    result = {
        event: "close"
    };
  • upload-added - a file was selected for upload

    result = {
        event: "upload-added",
        info: {
          file: { lastModified, lastModifiedDate, name, size, type },
          publicId: "public-id" }
    };
  • queues-start - files are about to begin uploading

    result = {
        event: "queues-start"
    };
  • queues-end - all files have finished uploading

    result = {
        event: "queues-end"
    };
  • batch-cancelled - uploading was cancelled

    result = {
        event: "batch-cancelled",
        info: { reason: "MAX_EXCEEDED" | "INVALID_PUBLIC_ID" }
    };
  • source-changed - user selected a different source

    result = {
        event: "source-changed",
        info: { source: "local" | "url" | "facebook"   //etc.   
    }};
  • tags - the contents of the tags input field (Advanced options) changed

    result = {
        event: "tags",
        info: {
          tags: ["dog", "family", "home"] }   //tags currently in the field
    };
  • publicid - the contents of the public id input field (Advanced options) changed

    result = {
        event: "publicid",
        info: { id: "my-public-id" }
    };
  • widget-view-change - switched from expanded queue to minimized or vice versa

    result = {
        event: "widget-view-change",
        info: { type: 2 | 8    //2 = Expanded, 8 = Minimized   
    }};
  • retry - user retried after failed uploads

    result = {
        event: "retry",
        info: {
          ids: [],
          all: true | false   //whether retry-all was clicked
    }};
  • abort - user aborted upload

    result = {
        event: "abort",
        info: {
          ids: [],
          all: true | false   //whether abort-all was clicked
    }};
  • show-completed - user clicked the show completed button (requires 'showCompletedButton = true' widget option)

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

For example, to log a message to the console when a user clicks the 'show completed' button:

cloudinary.openUploadWidget({
  cloudName: "demo", uploadPreset: "preset1",
  showCompletedButton: true,  
  }, (error, result) => {
    const eventData = result.data;
    if (eventData.event === "show-completed") {
      eventData.info.items.forEach((item) => {
        console.log(`show completed for item with id: 
        ${item.uploadInfo.public_id}`); //uploadInfo is the data returned in the upload response
      });
    }
});

Pre-batch

If you need to run any pre-processing on the files in the upload queue before they are uploaded to your Cloudinary account, you can set the preBatch parameter with a function to run beforehand. If the code in your function determines that the upload should be canceled, you can include the cancel boolean parameter set to true when calling the callback function.

For example, to cancel the upload if the file name is 'TopSecret':

cloudinary.openUploadWidget({
  cloudName: "demo", uploadPreset: "preset1",
  preBatch: (data, cb) => {
    if (data.files[0].name === "TopSecret") {
      cb({cancel: true}); 
    }
    else { 
      cb() 
    }
  }, (error, result) => { });

Tagging suggestions

You can add tagging suggestions that appear while your users are typing in the Add a Tag (Advanced options) text field, by providing an optional function that is called whenever the text changes in the field. Your function should call the callback function with the list of tagging suggestions to display. Add the getTags parameter with the function to call, and make sure to also set the showAdvancedOptions parameter to true.

The following example demonstrates a mini auto-complete function that returns only suggestions matching the current text entered in the field:

const tags = ["extract", "amazing", "apple", "dog", "grass", "planes", "rocket", "rock", "movies", "music", "sad", "light", "open", "mosaic", "entertainment", "test", "testament", "beach", "vacation", "weather", "letter", "orchard"];
const getTags = (cb, prefix) =>
  cb(prefix ? tags.filter((t) => !t.indexOf(prefix)) : tags);

cloudinary.openUploadWidget({
  cloudName: "demo", uploadPreset: "preset1",
  showAdvancedOptions: true        
  getTags: getTags, //provide callback to retrieve tagging suggestions
  }, (error, result) => { });

Look and feel customization

The look & feel of the upload widget can be fully customized. You can modify the colors, fonts, and other elements by providing your own customization.

Custom styling is specified using the styles parameter, which accepts a JSON structure defining the default elements to override. Styles are further divided as follows:

  • palette for defining the colors of the various elements as an RGB or RGBA hex triplet or quadruplet, or a 3- or 4-digit RGB/RGBA hex.
  • fonts for defining the font to use for all the text elements. Currently the widget only supports fonts from Google (available via fonts.googleapis.com).

The following example sets all elements to their default values (for reference purposes) - in practice you only need to include the elements you want to override:

cloudinary.openUploadWidget({
  cloudName: "demo", uploadPreset: "preset1",
  styles:{
    palette: {
      window: "#FFF",
      windowBorder: "#90A0B3",
      tabIcon: "#0E2F5A",
      menuIcons: "#5A616A",
      textDark: "#000000",
      textLight: "#FFFFFF",
      link:  "#0078FF",
      action:  "#FF620C",
      inactiveTabIcon: "#0E2F5A",
      error: "#F44235",
      inProgress: "#0078FF",
      complete: "#20B832",
      sourceBg: "#E4EBF1"
    },
    fonts: {
        "'Cute Font', cursive": "https://fonts.googleapis.com/css?family=Cute+Font",
    }
  }, (error, result) => { });

Tip
Use the Upload Widget Demo page to visualize the upload widget customization options, and when you are happy with the colors you have selected, Copy the palette customization code to the clipboard.

Localization

The text used in the upload widget can be fully customized for different languages. The translations for each language are specified using the text parameter, which accepts a JSON structure defining the value to use for each text element in each language. The language parameter sets which of the language options to use from those defined in the text parameter (en by default).

The following example sets all the en elements to their default values (for reference purposes) - in practice you only need to include the elements you want to override:

cloudinary.openUploadWidget({
  cloudName: "demo", uploadPreset: "preset1",
  language = "en",  
  text = {
    en: {
        "queue": {
            "title": "Upload Queue",
            "title_uploading_with_counter": "Uploading {{num}} Assets",
            "title_uploading": "Uploading Assets",
            "mini_title": "Uploaded",
            "mini_title_uploading": "Uploading",
            "show_completed": "Show completed",
            "retry_failed": "Retry failed",
            "abort_all": "Abort all",
            "upload_more": "Upload More",
            "more": "More",
            "mini_upload_count": "{{num}} Uploaded",
            "mini_failed": "{{num}} Failed",
            "statuses": {
                "uploading": "Uploading...",
                "error": "Error",
                "uploaded": "Done",
                "aborted": "Aborted"
            }
        },
        "or": "Or",
        "advanced": "Advanced",
        "close": "Close",
        "no_results": "No Results",
        "search_placeholder": "Search files",
        "menu": {
            "files": "My Files",
            "web": "Web Address",
            "camera": "Camera",
            "gsearch": "Image Search",
            "gdrive": "Google Photos",
            "dropbox": "Dropbox",
            "facebook": "Facebook",
            "instagram": "Instagram"
        },
        "selection_counter": {
            "selected": "selected"
        },
        "actions": {
            "upload": "Upload",
            "clear_all": "Clear all",
            "log_out": "Log out"
        },
        "notifications": {
            "general_error": "An error has occurred",
            "general_prompt": "Are you sure?",
            "limit_reached": "No more files can be selected",
            "invalid_add_url": "Added URL must be valid",
            "invalid_public_id": "Public ID cannot contain \\,?,&,#,%,<,>",
            "no_new_files": "File(s) have already been uploaded"
        },
        "advanced_options": {
            "public_id_ph": "Public ID",
            "tags_ph": "Add a Tag",
            "add_new": "Add new tag: "
        },
        "landscape_overlay": {
            "title": "Landscape mode isn't supported",
            "description": "Rotate back to portrait mode to continue."
        },
        "camera": {
            "main_title": "Camera",
            "capture": "Capture",
            "cancel": "Cancel",
            "take_pic": "Take A Picture and Upload",
            "explanation": "Make sure your camera is connected, your browser allows camera capture. When ready, position yourself and click Capture",
            "camera_error": "Failed to access camera",
            "retry": "Retry Camera",
            "file_name": "Camera_{{time}}"
        },
        "dropbox": {
            "main_title": "Dropbox",
            "no_auth_title": "Upload files from your Dropbox account",
            "no_auth_action": "Connect to Dropbox",
            "no_photos": "No Photos",
            "no_files": "No Files",
            "root_crumb": "Root",
            "list_headers": {
                "select": "Select",
                "name": "Name",
                "modified": "Modified"
            },
            "menu": {
                "browse": "Browse",
                "recent": "Recent"
            },
            "authenticating": "Authenticating..."
        },
        "facebook": {
            "main_title": "Facebook",
            "no_photos": "No photos...",
            "no_auth_title": "Upload files from your Facebook account",
            "no_auth_action": "Connect to Facebook",
            "no_auth_statement": "We will not post anything without your permission",
            "album_subtitle": "{{count}} photos",
            "menu": {
                "uploaded": "Your Photos",
                "tagged": "Photos of You",
                "albums": "Albums"
            }
        },
        "google_drive": {
            "main_title": "Google Photos",
            "no_auth_title": "Upload files from your Google Photos",
            "no_auth_action": "Connect to Google Photos",
            "no_photos": "No Photos",
            "header_title": "Your Google Photos"
        },
        "image_search": {
            "main_title": "Image Search",
            "inputPlaceholder": "Search for images",
            "customPlaceholder": "Search {{site}}",
            "filters_title": "site",
            "rights": "Usage rights",
            "rights_options": {
                "not_filtered": "not filtered by license",
                "free": "free to use or share",
                "free_com": "free to use or share, even commercially",
                "free_mod": "free to use share or modify",
                "free_mod_com": "free to use, share or modify, even commercially"
            },
            "search_error": "Search failed, please try again."
        },
        "instagram": {
            "main_title": "Instagram",
            "no_auth_title": "Upload photos from your Instagram account",
            "no_auth_action": "Connect to Instagram",
            "header_title": "Your Recent Instagram Photos",
            "authenticating": "Authenticating..."
        },
        "local": {
            "main_title": "Upload Files"
        }
    }
  }, (error, result) => { });

Note
The elements above that support a variable (specified inside double braces {{...}}) are replaced with the actual value at runtime. No other elements support variables.

Upload widget options

The following table lists all available upload widget options.

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

Option name Type Description
Required:
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 conversly, 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 in the Upload tab of the conold settings or using the Admin API.
Example: preset1
Widget behavior:
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, imageSearch, facebook, instagram
Notes:
- 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.
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, only the first maxImages files will be uploaded.
Default: null.
Example: 10
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
croppingAspectRatio Decimal If specified, enforce the given aspect ratio on the selected region when performing interactive cropping. Relevant only if cropping is enabled.
The aspect ratio is defined as width/height. For example, 0.5 for portrait oriented rectangle or 1 for square.
Default: null
Example: 0.5
croppingDefaultSelectionRatio Decimal Initialize the size of the cropping selection box to a different value from the default.
Relevant only if the cropping feature is enabled.
The croppingDefaultSelectionRatio value is calculated as a proportion of the image's size.
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. Relevant only if the cropping feature is enabled.
custom: the selected region is set as the customCoordinates upload parameter (default).
face: the selected region is set as the faceCoordinates upload parameter.
croppingShowBackButton Boolean Whether to show a Back button when in cropping mode. Relevant only if the cropping feature is enabled.
Default: true
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 imageSearch 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.
Upload parameters:
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 actions:
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: 1500000 (1.5 MB)
Notes:
- 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 40MB (the files can still be uploaded).
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 5MB (5000000).
Default: 20000000
Containing page update:
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 Map 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, a map of transformations parameters or an array of chained 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"
Customization:
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:
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 An optional function that is called for adding tagging suggestions whenever the text changes in the Add a Tag Advanced text field.
preBatch Function A function that performs pre-batch processing 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 enabled users to set the Public ID and Add a Tag. 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
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 pixels from that edge. Default right:35
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');