jQuery uploading widget v2 JavaScript API Documentation

You may not need all of the features that the jQuery widget exhibits. Or, perhaps, you want to redesign the user experience, but don’t want to reinvent the wheel. Or the task is simply to build some UI on top of the widget. For all these use cases we provide a JavaScript API. Use it to control the default widget, or do stuff without it via standalone components that can be combined with your own solutions.


Uploading Widget can handle one file (single-upload) or multiple files at once (multi-upload).

Initializes widget instances once (either single-upload, or multi-upload) on every element with role="uploadcare-uploader" attribute in a container, specified by selector or DOM element. If container is absent the document is used. Returns array of new initialized widgets, or empty array if no new instances were initialized.

var widgets = uploadcare.initialize('#my-form');
widgets; // [widget1, widget2, multipleWidget1, ...]
var widgets = uploadcare.initialize();javascript

This method is called automatically unless manual start is defined.

Get the widget instance for a given element.

var singleWidget = uploadcare.SingleWidget('[role=uploadcare-uploader]');javascript

Element argument can be a DOM element, a jQuery object, or a CSS selector. If element’s argument is a CSS selector, only the instance for the first matched element will be returned. To make sure you get the right instance when there are multiple widgets on the page, select by id or pass in a DOM element.

All options will be loaded from element’s data-attributes on the first initialization.

If passed element has data-multiple attribute, an error will be raised. Multi-upload Uploading Widget should be used in this case.

Get the multiple widget instance for a given element with the data-multiple option turned on.

var multiWidget = uploadcare.MultipleWidget('[role=uploadcare-uploader][data-multiple]');javascript

Works the same as the constructor for single-upload Uploading Widget. If an instance of the first element is not a multi-upload widget, error is raised.

Get the single or multiple widget instance depending on data-multiple attribute. The API for single and multiple widgets is slightly different. Use this constructor when the code can work with both of them.

var widget = uploadcare.Widget('[role=uploadcare-uploader]');javascript

Set a file instance as a value for the single-upload Uploading Widget.


Set a file UUID or a CDN link as a value.


Set null as a value to clear the widget.


Set a group instance as a value for the multi-upload Uploading Widget.


Set an array of file instances or UUIDs as a value for the multi-upload Uploading Widget.

multiWidget.value([file1, file2, '9dd2f080-cc52-442d-aa06-1d9eec7f40d1']);javascript

Set a file group identifier as a value for the multi-upload Uploading Widget.


Get current widget value: file instance, group instance or null.

var file = widget.value();javascript

Load new file or group instance from value attribute of the input (by UUID or CDN link), and update information about the object from Uploadcare servers.


Open the dialog of a specific widget and get its instance. Result is dialog API.

var dialog = widget.openDialog(tab);javascript

tab — name of a tab opened by default.

Do something after a new file is selected. An instance is passed to the callback: file for single-upload Uploading Widget, or file group for multi-upload Uploading Widget.

It may or may not be uploaded.

widget.onChange(function(file) {
  // Handle new file.

Do something **after a file is uploaded and ready.** The callback is passed an info object: [file info](#file-info) for [single-upload Uploading Widget](#file-widget), or [file group info](#file-group-info) for [multi-upload Uploading Widget](#file-multiple-widget).
widget.onUploadComplete(function(info) {
  // Handle uploaded file info.

// Same as above:
widget.onChange(function(file) {
  if (file) {
    file.done(function(info) {
      // Handle uploaded file info.

Do something when dialog is opened (either by user’s click or from widget.openDialog call). Works only when system dialog is not enabled.

widget.onDialogOpen(function(dialogApi) {

Unsubscribe any callback.

widget.onChange(fn); // Subscribe
widget.onChange.remove(fn); // Unsubscribe



Files and Uploads

Uploading Widget and Javascript API works with the file instances, which implement jQuery promise interface.

Wait when the file is ready. Returns fileInfo object.

file.done(function(fileInfo) {
  // Upload successfully completed and file is ready.
}).fail(function(error, fileInfo) {
  // Upload failed or something else went wrong.

Watch for the file uploading progress. Returns uploadInfo object.

file.progress(function(uploadInfo) {
  // State of upload is updated.
  // This callback is invoked at least once with current state,
  // immediately after assignment.

Show file upload progress on a jQuery UI progressbar.

file.progress(function(uploadInfo) {
  $('#progress').progressbar('value', uploadInfo.progress);

A new file instance can be constructed by calling fileFrom factory function. First argument is one of the predefined identifiers, second is the file source. Depending on the identifier, the function can start file uploading or just return an instance of already uploaded file.

Upload a new file from an arbitrary URL.

var file = uploadcare.fileFrom('url', 'http://example.com/image.png');javascript

Upload a new file from a native file object. This method supports uploading large files (> 100MB) and upload progress, but it is not available on outdated browsers (see browsers support).

var file = uploadcare.fileFrom('object', input.files[0]);javascript

Upload new file from input DOM element. This method works in all browsers, but does not support large files and uploading progress.

var file = uploadcare.fileFrom('input', input);javascript

Create a file instance from an uploaded file UUID or a CDN link and load info from Uploadcare server.

var file = uploadcare.fileFrom('uploaded', '61783708-7090-4d6a-b82b-81f98e40a327');javascript

Cancel any in-progress upload immediately and stop all events.



Structure of the fileInfo object:






File UUID.



Original name of the uploaded file.



File size in bytes.



true, if the file is stored in our storage, false otherwise.



true, if the file is an image, false otherwise.



Public file CDN URL, may contain CDN operations.



URL part with applied CDN operations or null. Appear after user crops image, for example.



Public file CDN URL without any operations.



Object with original image properties if file is image, null otherwise.


  • width and height
  • format — JPEG, PNG or other
  • datetime_original, geo_location and orientation from EXIF
  • dpi — value from format properties or from EXIF, if available



Object with information about file source. For example this can be name of social network, public link if any, owner’s user name etc. This information is not stored on our servers and available only on the page where file was uploaded.


Structure of the uploadInfo object:






Current readiness state: 'uploading', 'uploaded', or 'ready'.



Upload progress as a value from 0 to 1.



File readiness (sum of upload progress and info preparation progress) as a value from 0 to 1.

The error argument in the fail callback is one of the following values, or a user-defined value, raised in the validators.

  • 'baddata' — invalid argument passed to file constructor
  • 'size' — file size is too large
  • 'upload' — error during upload
  • 'user' — upload cancelled
  • 'info' — error when fetching file information
  • 'deleted' — file was deleted (possible in a group)

File Group

Group is an ordered collection of file instances. Once it is created, it can’t be modified, but you always can create a new group with the same files.

Create a group from an array of files and/or other groups.

var fileGroup = uploadcare.FileGroup([file1, fileGroup1, file2]);javascript

After a group instance is created, it can be uploaded to Uploadcare server by calling promise method.

Subscribe to the group upload events. Wait until all files are uploaded and a group is created.

var groupPromise = fileGroup.promise();
groupPromise.done(function(fileGroupInfo) {
  // Upload successfully completed and all files in the group are ready.
groupPromise.fail(function(error, fileGroupInfo) {
  // Upload failed or something else went wrong.

Watch for total uploading progress.

groupPromise.progress(function(uploadInfo) {
  // State of upload is updated.
  // This callback is invoked at least once with current state,
  // immediately after assignment.

Get group files as an array.

var arrayOfFiles = fileGroup.files();javascript

Get file infos in order of readiness.

$.each(arrayOfFiles, function(i, file) {
  // Wait for file uploading.
  file.done(function(fileInfo) {
    // i is file positon in group.
    console.log(i, fileInfo);

Get file infos in the order they are presented in the group.

$.when.apply(null, arrayOfFiles).done(function() {
  // Info for each file will be passed as an argument.
  var fileInfos = arguments;
  $.each(fileInfos, function(i, fileInfo) {
    // i is file position in the group.
    console.log(i, fileInfo);

Load a group from CDN via its identifier or CDN URL.

  .done(function(fileGroup) {
    // Group creation completed successfully.
  .fail(function() {
    // Something went wrong.


Structure of the fileGroupInfo object:

uuidstringFile group identifier.
namestringLocalized group size string, e.g. “5 files”.
sizenumberCumulative files size in bytes.
isStoredbooleantrue if all files in the group are stored, false otherwise.
isImagebooleantrue if all files in the group are images, false otherwise.
cdnUrlstringPublic file group CDN URL.

Files Validation

Validators allow restricting user choice to certain kind of files. For example you may want to accept only files that are less than 2mb or only PDF documents. Validator is a function that receives fileInfo object for each uploaded file and should throw exception if the file does not meet requirements.

function imagesOnly(fileInfo) {
  if (fileInfo.isImage === false) {
    throw new Error('image');

Validators are called as soon as new information about the file becomes available. All fields unknown at the calling time are null. This means one validator can be called more than once for one file and should test if validated field is not null.

function maxDimensions(width, height) {
  return function(fileInfo) {
    var imageInfo = fileInfo.originalImageInfo;
    if (imageInfo !== null) {
      if (imageInfo.width > width || imageInfo.height > height) {
        throw new Error('dimensions');

Validation in widget

Validators for the widget can be added to the validators property of Uploading Widget instances (both single or multiple).

var widget = uploadcare.Widget('#uploadcare-file');

widget.validators is regular javascript array. One widget can have several assigned validators. One validator can be ussigned to several widgets.

firstWidget.validators.push(maxSize(1024 * 1024));
firstWidget.validators.push(maxDimensions(800, 600));
firstWidget.validators; // [function imagesOnly(){...}, function () {...}, function () {...}]javascript

Note that you can’t rewrite it with another object. If you don’t need some validators, you need to remove them from original array.

// Leave only first two validators:
widget.validators = widget.validators.splice(0, 2); // WRONG!
widget.validators.splice(2);  // Correct.

// Remove all validators:
widget.validators = [];       // WRONG!
widget.validators.length = 0; // Correct.javascript

Validation in javascript API

You can add validators array to settings objects for all API functions where this makes sense.

uploadcare.openDialog(null, {
  validators: [
    maxSize(1024 * 1024),
    minDimensions(800, 600)

The list of functions includes but is not limited to openDialog, openPanel, fileFrom, filesFrom, dragdrop.uploadDrop, dragdrop.receiveDrop.

You should use validators instead of checking file properties in widget.onChange and widget.onUploadComplete callbacks, as validators work before dialog is closed thus improving user experience.

Argument in Error’s constructor is a key in the localization file for a message shown to the user. The key can be one of the common errors, i.e. size, image (see localization file), or you can add a new message via custom localization.

You can find useful examples in cookbook.

Upload Dialog and Panel

Upload dialog is modal window on top of the page. It contains set of tabs with different files sources or file preview. Upload panel is the same thing but in non-modal form.

Open a standalone upload dialog over page.

var dialog = uploadcare.openDialog(files, tab, settings);javascript

files — a file, array of files or group of files which will be shown as already uploaded.

tab — optional, name of tab opened by default (if no files uploaded).

settingssettings object.

Open a panel in specified place.

var panel = uploadcare.openPanel(container, files, tab, settings);javascript

container — selector or DOM element which will be replaced with panel and will be placed back after panel resolving.

files — a file, array of files or group of files which will be shown as already uploaded.

tab — optional, name of tab opened by default (if no files uploaded).

settingssettings object.

Dialog API

Both panel and dialog instances implement extended jQuery promise interface with progress on user switch tab.

dialog.done(function(result) {
  // Dialog closed and file or file group chosen.

dialog.fail(function(result) {
  // Dialog closed and no file or file group was selected.
  // The result argument is either null, or the last selected file.

dialog.always(function() {
  // Handle dialog closing, regardless of file selection.

dialog.progress(function(tabName) {
  // tabName is selected

In addtition to jQuery promise interface, dialog and panel objects have following properties and methods:






Resolve dialog with current selected files.



Close the dialog and discard file selection.



Add array of files to dialog result set.



Switch dialog to tab with given name. Name should be present in settings.tabs array.



Collection of selected files. Use it for subscribe to change events.



Hide tab with given name.



Show tab with given name.



Is tab with given name visible.



Register callback which will be called when a tab visibility is changed. The first argument will be tab name, the second is boolean: is tab visible.

You can find more examples in customization tutorial.

Custom Tabs

Besides buit-in tabs (file, url, dropbox, etc.) you can implement and add tab with custom behavior to dialog. This is relatively complex, but powerful way to customize dialog.

Register new tab with given name.

uploadcare.registerTab(name, constructor);javascript

name — name which can be used in tabs list.

constructor — function which will be called to create new tab.

Constructor is called each time when new dialog is opened. It should have the following declaration:
function myTab(container, button, dialogApi, settings, name) {

container — jQuery object with main tab element.

button — jQuery object with tab button.

dialogApiobject with useful methods to control dialog.

settingssettings object.

name — name used for registering tab and in tabs list. One constructor can be registered under several names.

You can find more examples in customization tutorial.

Drag and drop

This boolean parameter is set to true if browser supports drag and drop and file API.

var browser_supports_dragdrop = uploadcare.dragdrop.support;javascript

Get file objects after dropping them on el element. el can be DOM element, selector or jQuery object.

uploadcare.dragdrop.uploadDrop(el, callback[, settings]);javascript

For instance, one file will be uploaded (if you put more than one file, it will be the first of them)

uploadcare.dragdrop.uploadDrop(el, function(file) {

or all files will be uploaded

uploadcare.dragdrop.uploadDrop(el, function(files) {
  files; // array
}, {multiple: true});javascript

settings is settings object.

Get raw data after dropping files on el element. el can be DOM element, selector or jQuery object.

uploadcare.dragdrop.receiveDrop(el, callback);javascript

For example:

uploadcare.dragdrop.receiveDrop(el, function(type, data) {
  type; // 'object' or 'url'
  data; // Array of native File objecs or URLs.

  // File retrieving (or the first file retrieving if there are some)
  var file = uploadcare.fileFrom(type, data[0]);

  // Retrieving of all files
  var fileArray = uploadcare.filesFrom(type, data);

Source tabs styling

Uploading Widget and dialog appear on your pages and you can easily override their style via CSS. But some tabs (Facebook, Instagram, etc.) are open in iframe from our domain. You can use these methods to add custom styles to such tabs.

Add plain css code to tabs. Use classes to select specific tab.

var style = ".source-facebook .main-content {background: #98AFD5;}";

Add css file to tabs. File url should be absolute.


Please note due to the fact that tabs are open via https, there is no way to add css file via http. If your site does not support https you can use third-party hosting with https support for such files. Amazon S3 is a good option.