API

Initialization

The basic initialization of the File Upload widget is by calling the fileupload method on a jQuery collection with the target HTML element (usually a container element holding the file upload form, or the file upload form itself):

$('#fileupload').fileupload();

The method accepts an object as first argument that allows to initialize the widget with various Options:

$('#fileupload').fileupload({
    url: '/path/to/upload/handler.json',
    sequentialUploads: true
});

Data attributes

It is possible to initialize the file upload widget using HTML5 data attributes:

<input id="fileupload" type="file" name="files[]" multiple
    data-url="/path/to/upload/handler.json"
    data-sequential-uploads="true"
    data-form-data='{"script": "true"}'>

/* Initializes the File Upload widget with
{
    url: '/path/to/upload/handler.json',
    sequentialUploads: true,
    formData: {script: true}
}
*/
$('#fileupload').fileupload();

Options

It is possible to change Options after initializing the widget:

$('#fileupload').fileupload(
    'option',
    'url',
    '/path/to/upload/handler.json'
);

If no value is specified, the option method acts as a getter:

var dropZone = $('#fileupload').fileupload(
    'option',
    'dropZone'
);

Multiple Options can be set at once by providing an object as second parameter:

$('#fileupload').fileupload(
    'option',
    {
        url: '/path/to/upload/handler.json',
        sequentialUploads: true
    }
);

Deinitialization

To remove the file upload widget functionality from the element node, call the destroy method:

$('#fileupload').fileupload('destroy');

This will also remove any added event listeners.

Disable/Enable

As other widgets based on jQuery UI Widget, the File Upload widget can be disabled/enabled:

$('#fileupload').fileupload('disable');

$('#fileupload').fileupload('enable');

Programmatic file upload

Usually, file uploads are invoked by selecting files via file input button or by dropping files on the drop zone.

However it is also possible to upload files programmatically for browsers with support for XHR file uploads (see Browser support):

$('#fileupload').fileupload('add', {files: filesList});

The second argument must be an object with an array (or array-like list) of File or Blob objects as files property.
Other properties allow to override options for the file upload, e.g. the upload url:

$('#fileupload').fileupload('add', {files: filesList, url: '/path/to/upload/handler.json'});

The add method uploads files by adding them to the upload queue, the same way that files are added via the file input button or drag&drop.
Files can also be sent directly using the send method:

$('#fileupload').fileupload('send', {files: filesList});

The send method returns a jqXHR object, that allows to bind callbacks to the ajax file upload request(s):

var jqXHR = $('#fileupload').fileupload('send', {files: filesList})
    .success(function (result, textStatus, jqXHR) {/* ... */})
    .error(function (jqXHR, textStatus, errorThrown) {/* ... */})
    .complete(function (result, textStatus, jqXHR) {/* ... */});

Note: The send API method sends the given files directly, without splitting them up into multiple requests. So if your files argument is made up of 3 files, it will still only send one request. If the multipart option is true, it will still send all 3 files as part of one multipart request, else it will only send the first file.
So if you need to send files with multiple requests, either call the send API method multiple times, or use the add API method instead.

Programmatic file uploads for browsers without support for XHR file uploads

It is also possible to use the add and send API methods for browsers without support for XHR file uploads, by making use of the fileInput option:

$('#some-file-input-field').bind('change', function (e) {
    $('#fileupload').fileupload('add', {
        files: [{name: this.value}],
        fileInput: $(this)
    });
});

The fileInput property must be a jQuery collection with an input of type file with a valid files selection. The files property has to reflect the files selection with an array of objects with a name property for each selected file, but the objects don't have to be of type File or Blob.

Non-XHR file uploads make use of the Iframe Transport.

Image resizing

If you include the file processing plugin, the following additional API is available:

$('#fileupload').fileupload('process', {
    // An array of image files that are to be resized:
    files: files,
    process: [
        {
            action: 'load',
            fileTypes: /^image\/(gif|jpeg|png)$/,
            maxFileSize: 20000000 // 20MB
        },
        {
            action: 'resize',
            maxWidth: 1920,
            maxHeight: 1200,
            minWidth: 800,
            minHeight: 600
        },
        {
            action: 'save'
        }
    ],
}).done(function () {
    // Resized image files have been converted in place
    // and are available in the given files array
});

The process method returns a Promise object, that allows to bind callbacks (like the "done" handler in the code snippet above) for the file processing completion.

Note: Image resizing is currently only supported by the latest versions of Google Chrome and Mozilla Firefox.

Callbacks

The File Upload widget provides several callback hooks.
One way of using them is to provide callback methods as part of the Options object:

$('#fileupload').fileupload({
    drop: function (e, data) {
        $.each(data.files, function (index, file) {
            alert('Dropped file: ' + file.name);
        });
    },
    change: function (e, data) {
        $.each(data.files, function (index, file) {
            alert('Selected file: ' + file.name);
        });
    }
});

The second way of using them is by binding event listeners to the widget element:

$('#fileupload')
    .bind('fileuploaddrop', function (e, data) {/* ... */})
    .bind('fileuploadchange', function (e, data) {/* ... */});

Each event name has "fileupload" as prefix.

Note: Adding additional event listeners via bind method is the preferred option to preserve callback settings by the jQuery File Upload UI version.

One special callback is the add callback, as it provides a submit method for the data argument, that will start the file upload:

$('#fileupload').fileupload({
    add: function (e, data) {
        data.submit();
    }
});

The submit method of the data argument given to the add callback returns a jqXHR object, that allows to bind callbacks to the ajax file upload request:

$('#fileupload').fileupload({
    add: function (e, data) {
        var jqXHR = data.submit()
            .success(function (result, textStatus, jqXHR) {/* ... */})
            .error(function (jqXHR, textStatus, errorThrown) {/* ... */})
            .complete(function (result, textStatus, jqXHR) {/* ... */});
    }
});

How to cancel an upload

Uploads can be canceled by invoking the abort method on a jqXHR object:

var jqXHR = $('#fileupload').fileupload('send', {files: filesList})
    .error(function (jqXHR, textStatus, errorThrown) {
        if (errorThrown === 'abort') {
            alert('File Upload has been canceled');
        }
    });
$('button.cancel').click(function (e) {
    jqXHR.abort();
});