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.
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();
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:
+-------------------+---------+-------------------------------------------------------------------+
| Property | Type | Value |
+===================+=========+===================================================================+
| uuid | string | File UUID. |
+-------------------+---------+-------------------------------------------------------------------+
| name | string | Original name of the uploaded file. |
+-------------------+---------+-------------------------------------------------------------------+
| size | number | File size in bytes. |
+-------------------+---------+-------------------------------------------------------------------+
| isStored | boolean | true
, if the file is stored in our storage, false
otherwise. |
+-------------------+---------+-------------------------------------------------------------------+
| isImage | boolean | true
, if the file is an image, false
otherwise. |
+-------------------+---------+-------------------------------------------------------------------+
| cdnUrl | string | Public file CDN URL, may contain |
| | | CDN operations. |
+-------------------+---------+-------------------------------------------------------------------+
| cdnUrlModifiers | string | URL part with applied CDN operations |
| | | or null. Appear after user crops image, for example. |
+-------------------+---------+-------------------------------------------------------------------+
| originalUrl | string | Public file CDN URL without any operations. |
+-------------------+---------+-------------------------------------------------------------------+
| originalImageInfo | object | Object with original image properties if file is image, |
| | | null otherwise. |
| | | |
| | | Properties: |
| | | * 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 |
+-------------------+---------+-------------------------------------------------------------------+
| sourceInfo | object | 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. |
+-------------------+---------+-------------------------------------------------------------------+
uploadInfo
Structure of the uploadInfo
object:
+----------------+--------+-------------------------------------------+
| Property | Type | Value |
+================+========+===========================================+
| state | string | Current readiness state: 'uploading'
, |
| | | 'uploaded'
, or 'ready'
. |
+----------------+--------+-------------------------------------------+
| uploadProgress | number | Upload progress as a value from 0 to 1. |
+----------------+--------+-------------------------------------------+
| progress | number | 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]);
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');
}
}
};
}
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.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:
+-------------------+------------+---------------------------------------------------+
| Property | Type | Value |
+===================+============+===================================================+
| resolve() | method | Resolve dialog with current selected files. |
+-------------------+------------+---------------------------------------------------+
| reject() | method | Close the dialog and discard file selection. |
+-------------------+------------+---------------------------------------------------+
| addFiles() | method | Add array of files to dialog result set. |
+-------------------+------------+---------------------------------------------------+
| switchTab() | method | Switch dialog to tab with given name. Name should |
| | | be present in settings.tabs
array. |
+-------------------+------------+---------------------------------------------------+
| fileColl | collection | Collection of selected files. Use it |
| | | for subscribe to change events. |
+-------------------+------------+---------------------------------------------------+
| hideTab() | method | Hide tab with given name. |
+-------------------+------------+---------------------------------------------------+
| showTab() | method | Show tab with given name. |
+-------------------+------------+---------------------------------------------------+
| isTabVisible() | method | Is tab with given name visible. |
+-------------------+------------+---------------------------------------------------+
| onTabVisibility() | callback | 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);
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.