jQuery uploading widget v2 JavaScript API Documentation

This is for the version 2.x of the widget. If you’re looking for the widget v3 docs, check here
Learn how to migrate from v2 to v3.

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();

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]');

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]');

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]');

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

singleWidget.value(file);

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

singleWidget.value('9dd2f080-cc52-442d-aa06-1d9eec7f40d1');

Set null as a value to clear the widget.

singleWidget.value(null);

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

multiWidget.value(fileGroup);

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']);

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

multiWidget.value('cdf2fe62-3d43-47d4-9288-c3951561f5c7~2');

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

var file = widget.value();

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.

widget.reloadInfo();

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

var dialog = widget.openDialog(tab);

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 for single-upload Uploading Widget, or file group info for multi-upload Uploading 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) {
  dialogApi.switchTab('dropbox');
});

Unsubscribe any callback.

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

widget.onUploadComplete(fn);
widget.onUploadComplete.remove(fn);

widget.onDialogOpen(fn);
widget.onDialogOpen.remove(fn);

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');

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]);

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);

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');

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

file.cancel();

fileInfo

Structure of the fileInfo object:

uploadInfo

Structure of the uploadInfo object:

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]);

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();

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.

uploadcare.loadFileGroup('cdf2fe62-3d43-47d4-9288-c3951561f5c7~2')
  .done(function(fileGroup) {
    // Group creation completed successfully.
  })
  .fail(function() {
    // Something went wrong.
  });

fileGroupInfo

Structure of the fileGroupInfo object:

Property	Type	Value
uuid	string	File group identifier.
name	string	Localized group size string, e.g. “5 files”.
size	number	Cumulative files size in bytes.
isStored	boolean	`true` if all files in the group are stored, `false` otherwise.
isImage	boolean	`true` if all files in the group are images, `false` otherwise.
cdnUrl	string	Public 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');
      }
    }
  };
}

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.push(imagesOnly);

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

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

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.

Validation in javascript API

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

uploadcare.openDialog(null, {
  validators: [
    imagesOnly,
    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);

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).

settings — settings object.

Open a panel in specified place.

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

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).

settings — settings 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:

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);

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.

dialogApi — object with useful methods to control dialog.

settings — settings 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;

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

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

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) {
  file.done(...);
});

or all files will be uploaded

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

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);

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;}";
uploadcare.tabsCss.addStyle(style);

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

uploadcare.tabsCss.addUrl("https://site.com/styles/uc.tabs.css");

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.

jQuery uploading widget v2 JavaScript API Documentation

Widget

Files and Uploads

fileInfo

uploadInfo

File Group

fileGroupInfo

Files Validation

Validation in widget

Validation in javascript API

Upload Dialog and Panel

Dialog API

Custom Tabs

Drag and drop

Source tabs styling