jQuery image and video upload

There are several options for uploading media directly from your Web application to your Cloudinary account. You can also use an upload preset in conjunction with your chosen upload option to define the upload parameters. For details on all available upload options and parameters, see the Upload Images and Upload Videos documentation and the Upload method of the Upload API Reference.

Upload widget

Cloudinary's Upload widget is an interactive, feature rich, simple to integrate method to add Cloudinary upload support to your website. The widget allows you to upload resources to Cloudinary via a readymade interface that can be easily embedded within your web application with just a few lines of code, eliminating the need to develop in-house interactive upload capabilities. See the Upload widget documentation for detailed information.

The rest of the information on this page is only needed if you want to develop your own upload capability.

Direct uploading from the browser

Direct uploading from the browser allows your users to upload images directly from the browser or a mobile application instead of going through your servers. This method allows for faster uploading and a better user experience for your visitors. It also reduces load from your servers and reduces the complexity of your applications. Direct uploading is done using modern HTML5 cross origin resource sharing CORS and gracefully degrades to a seamless iframe based solution for older browsers. You can either use a signed upload that also requires generating an authentication signature on your backend, or use an unsigned upload with a restricted set of functionality.

Signed upload

Signed uploads require an authentication signature to be generated on your backend, and as such, jQuery signed upload with backend support should be implemented in conjunction with one of Cloudinary's backend frameworks (Rails, PHP, django, etc). The various backend frameworks implement helpers to be used in conjunction with jQuery to embed a file upload field in the HTML (e.g., cl_image_upload_tag) as well as automatically generate the authentication signature for the upload.

Unsigned upload

Unsigned upload is an option for performing upload without the need to generate a signature. However, for security reasons, only this restricted set of upload parameters can be specified directly when performing unsigned upload calls.

Unsigned upload options are controlled by an upload preset, so in order to use this feature you first need to enable unsigned uploading for your Cloudinary account from the Upload Settings page. An upload preset is used to define which upload options will be applied to images that are uploaded unsigned with that preset specified. You can edit the preset at any point in time (or create additional upload presets), to define the parameters that will be used for all images that are uploaded unsigned from user browsers or mobile applications.

Implementing unsigned direct uploading entails the following steps:

  1. Build a file input tag to upload a file directly to your Cloudinary account.
  2. Initialize the file input fields to perform direct uploading to the cloud.


1. Build a file input tag

A file input tag, containing Cloudinary's upload parameters, needs to be added to the form on your HTML page. Set the parameters of the file input field as follows:

  • name - set to "file".
  • type - set to "file".
  • class - set to "cloudinary-fileupload".
  • data-cloudinary-field - The name of an input field in your form to update post-upload with the image metadata. If no such field exists, a new hidden field with this name will be created. Upon a successful image upload, a jQuery event (cloudinarydone) is triggered on the input field and provides a fileupload data object (along with the result key containing received data from the cloudinary upload API) as the only argument.
  • data-form-data - The HTML-escaped JSON content including all the upload parameters: the mandatory parameters upload_preset and callback as well as any other parameters allowed by unsigned uploading.
    • The callback parameter should point to a public URL of your web application that has the cloudinary_cors.html file. It is included in the Cloudinary jQuery plugin package and is required for iframe fallback upload.
    • The upload_preset parameter must be the name of a preset that has been configured for unsigned uploading (mode = unsigned when configuring the preset via the management console).

Example of a file input field:

<input name="file" type="file" class="cloudinary-fileupload" data-cloudinary-field="image_id" 
   data-form-data=" ... html-escaped JSON data ... " ></input>

Example of unescaped JSON data:

{ "upload_preset":  "user_upload1", 
  "callback": "https://www.example.com/cloudinary_cors.html"}

Example of escaped JSON data for the data-form-data parameter (using the raw data above):

{ &quot;upload_preset&quot;:  &quot;user_upload1&quot;, 
  &quot;callback&quot;: &quot;https://www.example.com/cloudinary_cors.html&quot;}

2. Initialize file input fields

The Cloudinary jQuery library utilizes the Blueimp File Upload library to support uploading media directly from the browser. You must explicitly initialize all file input fields on your page to use this library with the cloudinary_fileupload method:

$(document).ready(function() {
  if($.fn.cloudinary_fileupload !== undefined) {
    $("input.cloudinary-fileupload[type=file]").cloudinary_fileupload();
  }
});

Upload multiple images

The file input field can be configured to support multiple file uploading simultaneously by setting the multiple HTML parameter. You should also manually bind an event handler to the cloudinarydone event to handle the results of multiple uploads.

Upload events

You can track the upload progress by binding an event handler to the following events: cloudinarydone, fileuploadsend, cloudinaryprogress, cloudinaryalways and cloudinaryprogressall. You can find more details and options in the documentation of jQuery-File-Upload.

Example 1: to bind an event handler to the cloudinarydone event and display a thumbnail preview of the uploaded image:

$('.cloudinary-fileupload').bind('cloudinarydone', function(e, data) {  
    $('.preview').html(
       $.cloudinary.imageTag(data.result.public_id, 
           { format: data.result.format, version: data.result.version, 
             crop: 'scale', width: 200 }));    
    $('.image_public_id').val(data.result.public_id);    
    return true;});

Example 2: to update a progress bar according to the data of the cloudinaryprogress event:

$('.cloudinary-fileupload').bind('cloudinaryprogress', function(e, data) { 
    $('.progress_bar').css('width', Math.round((data.loaded * 100.0) / data.total) + '%');});

Client side image validation before

Include the validation libraries and modify your script tags based on the the following example (order is important):

<script src="[folder-path]/jquery/dist/jquery.js" type="text/javascript"></script>
<script src="[folder-path]/jquery.ui/ui/widget.js" type="text/javascript"></script>
<script src="[folder-path]/blueimp-load-image/js/load-image.all.min.js"></script>
<script src="[folder-path]/blueimp-canvas-to-blob/js/canvas-to-blob.min.js"></script>
<script src="[folder-path]/blueimp-file-upload/js/jquery.iframe-transport.js" type="text/javascript"></script>
<script src="[folder-path]/blueimp-file-upload/js/jquery.fileupload.js" type="text/javascript"></script>
<script src="[folder-path]/blueimp-file-upload/js/jquery.fileupload-process.js"></script>
<script src="[folder-path]/blueimp-file-upload/js/jquery.fileupload-image.js" type="text/javascript"></script>
<script src="[folder-path]/blueimp-file-upload/js/jquery.fileupload-validate.js"></script>
<script src="[folder-path]/cloudinary-jquery-file-upload/cloudinary-jquery-file-upload.js" type="text/javascript"></script>
// [folder-path] is the mapping to the resources in your web application

The validation options are added when calling the cloudinary_fileupload method. For example:

$(document).ready(function() {
  $('.cloudinary-fileupload').cloudinary_fileupload({
    disableImageResize: false,
    imageMaxWidth: 800,                   // 800 is an example value - no default
    imageMaxHeight: 600,                  // 600 is an example value - no default
    maxFileSize: 20000000,                // 20MB is an example value - no default
    loadImageMaxFileSize: 20000000,       // default is 10MB
    acceptFileTypes: /(\.|\/)(gif|jpe?g|png|bmp|ico)$/i
  });
});

See the File Processing Options in the Blueimp File Upload wiki for more information.