jQuery uploading widget v2 JavaScript API Documentation

Widget

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.

singleWidget.value(file);javascript

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

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

Set null as a value to clear the widget.

singleWidget.value(null);javascript

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

multiWidget.value(fileGroup);javascript

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.

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

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.

widget.reloadInfo();javascript

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.
});javascript

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.
    });
  };
});javascript

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

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

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.
});javascript

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.
});javascript

Show file upload progress on a jQuery UI progressbar.

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

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.

file.cancel();javascript

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.
});javascript

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.
});javascript

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

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

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.
  });javascript

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

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

var widget = uploadcare.Widget('#uploadcare-file');
widget.validators.push(imagesOnly);javascript

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 () {...}]javascript

// 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

uploadcare.openDialog(null, {
  validators: [
    imagesOnly,
    maxSize(1024 * 1024),
    minDimensions(800, 600)
  ]
});javascript

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 dialog
• Open panel
• Dialog API

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

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

settings — settings object.

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

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.

function myTab(container, button, dialogApi, settings, name) {
  ...
}javascript

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

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

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

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

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

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.