Last updated: Nov-14-2022
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 Media upload documentation and the upload method of the Upload API Reference.
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 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 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:
- Build a file input tag to upload a file directly to Cloudinary.
- 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
callbackas well as any other parameters allowed by unsigned uploading.
callbackparameter should point to a public URL of your web application that has the
cloudinary_cors.htmlfile. It is included in the Cloudinary jQuery plugin package and is required for iframe fallback upload.
upload_presetparameter 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
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.
You can track the upload progress by binding an event handler to the following events:
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
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:
- File Processing Options in the Blueimp File Upload wiki.
- KB article on dynamically changing the payload of an upload request via Blueimp KB article.