JavaScript API — Widget Reference

• This is for the version 3.x of the widget. If you're looking for the widget v2 docs, check here
• Here’s how you migrate from v2 to v3.

Uploadcare Widget can handle either a single file upload or multiple files at once multi-upload. This section covers your JavaScript API widget workflow and methods.

• Widget initialization
• Single-file widgets
• Multi-file widgets
• Multi-purpose widgets
• Passing a single file to a widget
• Pass multiple files to a widget
• Get current widget value
• Load new file or group
• Open the widget dialog
• On change, widget event
• On upload complete, widget event
• On dialog open
• Unsubscribe widget callbacks

Widget initialization

Initialize a widget.

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

This is a one-time initialization of widget instances on every element with the role="uploadcare-uploader" attribute in a container specified by a selector or DOM element. Works for both single-file and multi-file widgets.

Returns an array of newly initialized widgets or an empty array in case no new instances were initialized.

The uploadcare.initialize() method is called automatically unless the manual start widget option is defined.

Single-file widgets

Get a single-upload widget instance for a given element.

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

uploadcare.SingleWidget() element argument can be a DOM element, jQuery object, or CSS selector. If an argument is a CSS selector, the method returns only an instance for the first matched element. To ensure you are getting the right instance when dealing with multiple widgets on a page, select by id or pass a DOM element to the method.

All widget options will be loaded from data-attribute of your element on a first widget initialization.

Passing an element with the data-multiple attribute to uploadcare.SingleWidget() raises an error. A multi-upload widget should be used instead.

Multi-file widgets

Get a multi-upload widget instance for a given element with the data-multiple option set.

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

The workflow is similar to single-upload widgets. If an instance of the first encountered element is not a multi-upload widget, an error is raised.

Multi-purpose widgets

Get either single-upload or multi-upload widget instance depending on the passed data-multiple attribute. While the API for single-upload and multi-upload widgets is slightly different, you can use this constructor when your code can work with both versions,

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

Pass a single file to a widget

Set a file instance as a value for a single-upload widget.

singleWidget.value(file);

You can also use a file UUID or CDN link as a value,

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

Setting null as a value clears the widget,

singleWidget.value(null);

Pass multiple files to a widget

Set a group instance as a value for a multi-upload widget.

multiWidget.value(fileGroup);

You can also set an array of file instances or UUIDs as a value for the multi-upload,

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

Or, just pass a valid file group identifier,

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

Get a current widget value

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

var file = widget.value();

Load a new file or group

Load a new file or group instance from the value attribute of your input or update the object info. You will get a UUID or CDN link.

widget.reloadInfo();

Open a widget dialog

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

var dialog = widget.openDialog(tab);

tab defines a name of the tab opened by default.

On change, widget event

Provides you with the ability to do something after a new file is selected. An instance is passed to the callback: a file for single-upload widgets or a file group for multi-upload widgets. The instance may or may not be uploaded.

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

On upload complete, widget event

Provides you with the ability to do something after a file is uploaded and ready. The callback is passed an info object: a file info for single-upload widgets or a file group info for multi-upload widgets.

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

On dialog open, widget event

Provides you with the ability to do something on widget dialog open. Works with a user click or the widget.openDialog() call. Works only when the system dialog option is disabled.

widget.onDialogOpen(function(dialogApi) {
  dialogApi.switchTab('dropbox');
});

Unsubscribe widget callbacks

Allows you to unsubscribe any widget callback,

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

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

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