Uploading Widget JavaScript API — Uploading Files

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

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

uuid

string

File UUID

name

string

Original filename

size

number

File size in bytes

mimeType

string

File's MIME-type

metadata

object

Arbitrary metadata associated with a file

isStored

boolean

true, if the file is stored in Uploadcare,
false otherwise

isImage

boolean

true, if the file is an image,
false otherwise.

cdnUrl

string

Public CDN URL related to a file, may contain CDN operations |

cdnUrlModifiers

string

A string holding existing URL modifiers, i.e. CDN operations in case those are | present. Null otherwise

originalUrl

string

Original file CDN URL with no modifiers

originalImageInfo

object

Object holding original image properties, if your file is an image, null otherwise. Properties:

  • width and height
  • format — JPEG, PNG, etc.
  • datetime_original, geo_location and orientation from EXIF
  • dpi — from either format properties or EXIF, if available
  • color_mode — image color mode

    Check out detailed API references for GET /info/, look for the image_info field of 200 response schema

originalVideoInfo

object

Object holding original video properties, if your file is a video, null otherwise. Properties:

  • duration — video file's duration in milliseconds
  • format — video file's format
  • bitrate — video file's bitrate
  • video — video stream's metadata
  • audio — audio stream's metadata, if available

    Check out detailed API references for GET /info/, look for the video_info field of 200 response schema

originalContentInfo

object

Object holding original file content properties, if available. Properties:

  • mime — object containing MIME type
  • image — object containing image metadata
  • video — object containing video metadata

    Check out detailed API references for GET /info/, look for the content_info field of 200 response schema

sourceInfo

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

state

string

Current upload states: 'uploading', 'uploaded', or 'ready'

uploadProgress

number

Upload progress as a value ranging from 0 to 1

progress

number

File ready state combines the progress of both upload and preparing info, as a value ranging from 0 to 1