jQuery uploading widget v3 JavaScript API Reference
On this page
- We’ve built the next version of the File Uploader.
Uploadcare Uploading Widget can handle either a single file upload or multiple files at once multi-upload. This section covers your JavaScript API Uploading Widget workflow and methods.
- Uploading Widget initialization
- Single-file Uploading Widget
- Multi-file Uploading Widget
- Multi-purpose Uploading Widget
- Passing a single file to a Uploading Widget
- Pass multiple files to a Uploading Widget
- Get current Uploading Widget value
- Load new file or group
- Open the Uploading Widget dialog
- On change, Uploading Widget event
- On upload complete, Uploading Widget event
- On dialog open
- Unsubscribe Uploading Widget callbacks
Uploading Widget initialization
Initialize an Uploading Widget.
var widgets = uploadcare.initialize('#my-form');
widgets; // [widget1, widget2, multipleWidget1, ...]
var widgets = uploadcare.initialize();
javascript
This is a one-time initialization of Uploading 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 Uploading Widgets.
Returns an array of newly initialized Uploading Widgets or an empty array in case no new instances were initialized.
The uploadcare.initialize()
method is called automatically unless the
manual start Uploading Widget option is defined.
Single-file Uploading Widgets
Get a single-upload Uploading Widget instance for a given element.
var singleWidget = uploadcare.SingleWidget('[role=uploadcare-uploader]');
javascript
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 Uploading Widgets on a page, select by id or pass a
DOM element to the method.
All Uploading Widget options will be loaded from data-attribute of your element on a first Uploading Widget initialization.
Passing an element with the data-multiple
attribute to uploadcare.SingleWidget()
raises an error. A multi-upload Uploading Widget should
be used instead.
Multi-file Uploading Widget
Get a multi-upload Uploading Widget instance for a given element with the data-multiple
option set.
var multiWidget = uploadcare.MultipleWidget('[role=uploadcare-uploader][data-multiple]');
javascript
The workflow is similar to single-upload Uploading Widget. If an instance of the first encountered element is not a multi-upload Uploading Widget, an error is raised.
Multi-purpose Uploading Widgets
Get either single-upload or multi-upload Uploading Widget instance depending on the passed
data-multiple
attribute.
While the API for single-upload and multi-upload Uploading Widgets is slightly different,
you can use this constructor when your code can work with both versions:
var widget = uploadcare.Widget('[role=uploadcare-uploader]');
javascript
Pass a single file to a Uploading Widget
Set a file instance as a value for a single-upload Uploading Widget.
singleWidget.value(file);
javascript
You can also use a file UUID or CDN link as a value:
singleWidget.value('9dd2f080-cc52-442d-aa06-1d9eec7f40d1');
javascript
Setting null
as a value clears the Uploading Widget:
singleWidget.value(null);
javascript
Pass multiple files to a Uploading Widget
Set a group instance as a value for a multi-upload Uploading Widget.
multiWidget.value(fileGroup);
javascript
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']);
javascript
Or, just pass a valid file group identifier:
multiWidget.value('cdf2fe62-3d43-47d4-9288-c3951561f5c7~2');
javascript
Get a current file uploader value
Get current file uploader value: file instance, group instance or null
.
var file = widget.value();
javascript
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();
javascript
Open a file uploader dialog
Open the dialog of a specific file uploader and get its instance. Returns a dialog API.
var dialog = widget.openDialog(tab);
javascript
tab
defines a name of the tab opened by default.
On change, file uploader 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 Uploading Widgets or a file group for multi-upload Uploading Widgets. The instance may or may not be uploaded.
widget.onChange(function(file) {
// Handle new file.
});
javascript
On upload complete, file uploader 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 Uploading Widgets or a file group info for multi-upload Uploading 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.
});
};
});
javascript
On dialog open, file uploader event
Provides you with the ability to do something on file uploader 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');
});
javascript
Unsubscribe file uploader callbacks
Allows you to unsubscribe any file uploader 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