jQuery image and video upload

There are several options for using jQuery to upload images and videos directly from your Web application to Cloudinary. 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 guide 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 JavaScript 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 jQuery upload from the browser allows your users to upload image and video assets 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, Python, 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 jQuery 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 from the Upload page of the Console Settings. 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 Cloudinary.
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 another input field in the same form that will be updated post-upload with the asset's metadata. If no such field exists in your form, a new hidden field with the specified name will be created. Upon successful upload, an 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 Cloudinary Console).

Example of a file input field:

Example of unescaped JSON data:

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

2. Initialize file input fields

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

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:

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

Client side image validation before upload

Include the validation libraries and modify your script tags as follows (order is important):

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