Uploading Widget JavaScript API — Uploading Files
On this page
- We’ve built the next version of the File Uploader.
Uploadcare Uploading Widget and JavaScript API work with file instances, which implement the jQuery promise interface. You can create a file instance via a new upload or by addressing existing files.
- Creating a new file instance
- Upload multiple files
- Wait until a file is available
- Checking the progress of a file upload
- Cancelling a file upload
- Object overview,
fileInfo
- Object overview,
uploadInfo
Creating a new file instance
A new file instance can be constructed by calling the fileFrom
function. Where
the first argument is one of the predefined identifiers, and the second argument
holds a file source. Depending on the passed identifier, the function can start
a new upload or return an instance of an existing file.
Note, you can also pass a settings
object to
fileFrom
as its third parameter.
File instance from URL
Uploading a file from URL is done by passing the url
identifier to the
fileFrom
function:
var file = uploadcare.fileFrom('url', 'http://example.com/image.png');
javascript
File instance from native object
Our JavaScript API supports uploading new files from
native file objects. This is done by passing the
object
identifier to the fileFrom
function.
var file = uploadcare.fileFrom('object', input.files[0]);
javascript
This method supports large file uploads (> 100MB) and checking upload progress. However, it will not work in outdated browsers, see browser support.
File instance from DOM
You can also upload files from input DOM elements. This is done by passing the
input
identifier to fileFrom
. Uploading from such inputs works in all browsers
but does not support large files and checking upload progress.
var file = uploadcare.fileFrom('input', input);
javascript
File instance from UUID or CDN URL
That is the case when a file instance is created from an existing file with
a UUID and hence a CDN URL. Any of those can be used as a file source
in fileFrom
.
The proper identifier to pass to the function here is uploaded
.
When using the uploaded
parameter, the widget fetches fileInfo
but doesn't clone/reupload the file.
var file = uploadcare.fileFrom('uploaded', '61783708-7090-4d6a-b82b-81f98e40a327');
javascript
Upload multiple files
This is a batch wrapper around fileFrom
.
First argument is a source type: url
, object
, input
or uploaded
.
The second argument is an array of sources of a specified type.
Returns an array of file instances.
var files = uploadcare.filesFrom('uploaded', [
'78ba53d2-b746-4f4f-a80f-6ca260c08cfe',
'80b55b77-6548-4799-808d-6e49415a5422'
]);
files.forEach(file => {
// file is a file instance
})
javascript
Wait until a file is available
Quite often, you want to ensure a file is there and ready before getting its instance. That is what the function is all about. It returns a fileInfo object.
file.done(function(fileInfo) {
// Upload has successfully completed and a file is ready.
}).fail(function(errorType, fileInfo, error) {
// Upload failed, or something else went wrong, a file is not ready.
// `errorType: string` - Indicates the reason or location of the error, e.g. `info`, `baddata` etc.
// `fileInfo: FileInfo` - File info object if known. Could be undefined.
// `error: XMLHttpRequest | { message: string; code: string }` - The error response from the server or XMLHttpRequest instance that threw the error. Could be undefined.
// See the list of all the possible error codes and it's messages:
// https://uploadcare.com/api-refs/upload-api/#tag/Errors
// `error` will be the instance of XMLHttpRequest in case when it's network error
// here is example of how to check it
const isNetworkError = error && 'readyState' in error
});
javascript
The error
argument in the fail
callback is one of the following values,
or a user-defined custom value, raised via validators.
'baddata'
, invalid argument passed to file constructor'size'
, file size is too large'upload'
, error during upload'user'
, upload was canceled'info'
, error when fetching file information'deleted'
, file was deleted, also applicable to groups and files within
Checking the progress of a file upload
When handling larger files, there is a sense in checking their upload progress.
The progress
function does exactly that and returns an
uploadInfo object.
file.progress(function(uploadInfo) {
// State of your upload gets updated.
// The callback is invoked at least once with a current state,
// right after assignment.
});
javascript
You can also show a file uploading progress via a jQuery UI progressbar.
file.progress(function(uploadInfo) {
$('#progress').progressbar('value', uploadInfo.progress);
});
javascript
Cancelling a file upload
Just use cancel
in case you want to immediately stop any in-progress upload and
all the events.
file.cancel();
javascript
Object overview, fileInfo
Here is how a fileInfo
object is structured,
Property | Type | Value |
---|---|---|
| string | File UUID |
| string | Original filename |
| number | File size in bytes |
| string | File's MIME-type |
| object | Arbitrary metadata associated with a file |
| boolean |
|
| boolean |
|
| string | Public CDN URL related to a file, may contain CDN operations | |
| string | A string holding existing URL modifiers, i.e. CDN operations in case those are | present. Null otherwise |
| string | Original file CDN URL with no modifiers |
| object | Object holding original image properties, if your file is an image,
|
| object | Object holding original video properties, if your file is a video,
|
| object | Object holding original file content properties, if available.
Properties:
|
| object | Object holding the info about a file source. For example, this can be a name of a social media, public URL, etc. We do not store such information hence it is only available on the page where your file uploading happens |
Object overview, uploadInfo
Here is how an uploadInfo
object is structured,
Property | Type | Value |
---|---|---|
| string | Current upload states: |
| number | Upload progress as a value ranging from 0 to 1 |
| number | File ready state combines the progress of both upload and preparing info, as a value ranging from 0 to 1 |