Upload widget

Overview

Cloudinary is a cloud-based service that allows uploading images (or any other files) to the cloud, from any source and at any scale. Cloudinary can dynamically process and manipulate uploaded images to match your graphic design and deliver these highly optimized to your users via a fast CDN.

Cloudinary's powerful image uploading APIs support uploads at scale from your server-side applications or directly from your users' browsers or mobile devices.

Cloudinary's upload widget

Cloudinary's upload widget is an interactive, feature rich, simple to integrate method to add Cloudinary support to your website. The widget, requiring just a single line of code to integrate, should eliminate the hassle of developing an in-house interactive image upload capabilities.

Cloudinary's widget includes a complete graphical interface. With it, a visitor can upload files from three different sources - one or more local images, a remote image (URL) or just snapping an image directly from the computer or mobile device's camera.

The widget supports a drag & drop functionality, interactive cropping, upload progress indication and thumbnail previews. The widget monitors and handles uploading errors.

The upload widget uploads your visitors images directly from their browsers over to Cloudinary, without burdening your servers in the process. The widget sends Javascript callbacks on successful uploads, so you can integrate the upload process back into your existing image pipeline with ease. You can configure Cloudinary to send server-side callbacks as well.

Once uploaded, images can be resized, cropped and manipulated by Cloudinary on-the-fly to be perfectly embedded back into your website or mobile app for viewing.

Cloudinary's upload widget requires pure Javascript to integrate and is easy to use with any web development framework. Advanced features are available using jQuery.

Quick example

In order to use Cloudinary's image upload widget in your site, simply include the the remote Javascript file of the widget (delivered optimized via a fast CDN) and specify the cloud_name of your Cloudinary account.

The following sample code binds to the click event of a link in a web page. The cloudinary.openUploadWidget method is called to programmatically open the upload widget when the opener link is clicked. When uploading is completed, the widget is automatically closed and a given Javascript callback function is called with a list of uploaded images as the result parameter.

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

<script src="//widget.cloudinary.com/global/all.js" type="text/javascript"></script>  
          
<script type="text/javascript">  
  document.getElementById("upload_widget_opener").addEventListener("click", function() {

    cloudinary.openUploadWidget({ cloud_name: 'demo', upload_preset: 'a5vxnzbp'}, 
      function(error, result) { console.log(error, result) });

  }, false);
</script>

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

The example above used standard Javascript code to open the widget and allows multiple image uploading. The following example uses jQuery this time for converting an existing link to a widget opener button. This time uploading to a certain folder and enabling interactive cropping of a single uploaded image.

<script src="//widget.cloudinary.com/global/all.js" type="text/javascript"></script>  
          
<script type="text/javascript">  
  $('#upload_widget_opener').cloudinary_upload_widget(
    { cloud_name: 'demo', upload_preset: 'a5vxnzbp', 
      cropping: 'server', 'folder': 'user_photos' },
    function(error, result) { console.log(error, result) });
</script>

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

Setup

Account setup

1. Create a Cloudinary account and copy your cloud name.
2. Enable unsigned uploading from the Upload Settings page of the management console. Copy the name of the created upload preset.

If you want to read more about upload presets, see the following articles: Direct upload made easy, from browser or mobile app to the cloud and Centralized control for image upload - image size, format, thumbnail generation, tagging and more .

Include widget script

HTTP URL:

HTTPS URL:

Protocol agnostic URL:

For example:

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

Including jQuery in your website is optional. It allows showing thumbnails of uploaded images and creating hidden fields with the identifiers of the uploaded images. The following example is a Javascript include line of the jQuery library.

<script src='//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js'></script>

API methods

The following Javascript method are publicly available for calling from your Website's code after including Cloudinary's upload widget Javascript file.

setCloudName(name)

Globally set the cloud name for all widget method calls.

For example:

<script src="http://widget.cloudinary.com/global/all.js" type="text/javascript">
</script>
<script>
  cloudinary.setCloudName('cadf1nga');
</script>

cloudinary.openUploadWidget(options, result_callback)

Programmatically create a widget frame and open it. options is a map of all widget options, including both client side settings and upload API parameters.

result_callback is an optional function called when the upload widget completes, either successfully uploading all images or when the widget is closed by user. The callback method is of the following signature function(error, result) . While error is either null if successful or an error message if there was a failure. result is an array of upload image infos, as returned by Cloudinary's upload API.

The method returns a widget object that has the following simple methods for opening and widget and closing it: open() and close().

For example:

cloudinary.openUploadWidget({upload_preset: 'a5vxnzbp'}, 
  function(error, result) {console.log(error, result)});

cloudinary.createUploadWidget(options, result_callback)

Same as openUploadWidget except that it creates a widget object and frame but does not display it until the open method of the returned widget object is called.

For example:

var widget = cloudinary.createUploadWidget({ upload_preset: 'a5vxnzbp' },
      function(error, result) {console.log(error, result)});

widget.open();

cloudinary.applyUploadWidget(element, options, result_callback)

Same as createUploadWidget except that it modifies the given element to be a nice 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'), 
  { upload_preset: 'a5vxnzbp' }, 
    function(error, result) {console.log(error, result)});

$.fn.cloudinary_upload_widget

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

For example:

$('#opener2').cloudinary_upload_widget({ upload_preset: 'a5vxnzbp' });

'cloudinarywidgetsuccess' - Global success event binding

If jQuery is loaded in your site, you can bind to the the cloudinarywidgetsuccess event for receiving success callbacks of all matching upload widgets in your page.

For example:

$(document).on('cloudinarywidgetsuccess', function(e, data) {
  console.log("Global", e, data);
});

'cloudinarywidgetdeleted' - Image deletion event binding

If jQuery is loaded in your site, you can bind to the the cloudinarywidgetdeleted event for receiving a callback when an image is deleted using the 'x' within the image thumbnail (after the image upload completes). The event receives an object that includes the details of the deleted image (resource_type, type, public_id).

For example:

$(document).on('cloudinarywidgetdeleted', function(e, data) {
  console.log("Public ID", data.public_id);
});

Look & feel customization

The look & feel of the upload widget can be fully customized. You can modify colors, fonts, icons and other elements by providing your custom CSS styles. In addition, Cloudinary provides predefined themes instead of the default one.

Custom styles are specified using the 'stylesheet' option. It accepts either a URL of a CSS file with style override instructions or inline style as a string. See the CSS files of the white and minimal themes as reference implementations.

A theme can be applied by setting the 'theme' option to the name of one of the following predefined themes:

'default'

'white'

'minimal'

'purple'

Upload widget options