A JavaScript library providing multiple simultaneous, stable
and resumable uploads via the HTML5 File API
Code on Github Download source Contribute

What is Resumable.js

It’s a JavaScript library providing multiple simultaneous, stable and resumable uploads via the HTML5 File API.

The library is designed to introduce fault-tolerance into the upload of large files through HTTP. This is done by splitting each files into small chunks; whenever the upload of a chunk fails, uploading is retried until the procedure completes. This allows uploads to automatically resume uploading after a network connection is lost either locally or to the server. Additionally, it allows for users to pause, resume and even recover uploads without losing state.

Resumable.js does not have any external dependencies other the HTML5 File API. This is relied on for the ability to chunk files into smaller pieces. Currently, this means that support is limited to Firefox 4+ and Chrome 11+.

Samples and examples are available in the samples/ folder. Please push your own as Markdown to help document the project.


How can I use it?

A new Resumable object is created with information of what and where to post:

var r = new Resumable({
  target:'/api/photo/redeem-upload-token', 
  query:{upload_token:'my_token'}
});
// Resumable.js isn't supported, fall back on a different method
if(!r.support) location.href = '/some-old-crappy-uploader';

To allow files to be either selected and drag-dropped, you’ll assign drop target and a DOM item to be clicked for browsing:

r.assignBrowse(document.getElementById('browseButton'));
r.assignDrop(document.getElementById('dropTarget'));

After this, interaction with Resumable.js is done by listening to events:

r.on('fileAdded', function(file){
    ...
  });
r.on('fileSuccess', function(file,message){
    ...
  });
r.on('fileError', function(file, message){
    ...
  });

How do I set it up with my server?

Most of the magic for Resumable.js happens in the user’s browser, but files still need to be reassembled from chunks on the server side. This should be a fairly simple task and can be achieved in any web framework or language, which is able to receive file uploads.

To handle the state of upload chunks, a number of extra parameters are sent along with all requests:

You should allow for the same chunk to be uploaded more than once; this isn’t standard behaviour, but on an unstable network environment it could happen, and this case is exactly what Resumable.js is designed for.

For every request, you can confirm reception in HTTP status codes:

Handling GET (or test() requests)

This will allow uploads to be resumed after browser restarts and even across browsers (in theory you could even run the same file upload across multiple tabs or different browsers). The POST data requests listed are required to use Resumable.js to receive data, but you can extend support by implementing a corresponding GET request with the same parameters:


Full documentation

Resumable

Configuration

The object is loaded with a configuation hash:

var r = new Resumable({opt1:'val', ...});

Available configuration options are:

Properties

Methods

Events

ResumableFile

Properties

Methods

Alternatives

This library is explicitly designed for modern browsers supporting advanced HTML5 file features, and the motivation has been to provide stable and resumable support for large files (allowing uploads of several GB files through HTTP in a predictable fashion).

If your aim is just to support progress indications during upload/uploading multiple files at once, Resumable.js isn’t for you. In those cases, SWFUpload and Plupload provides the same features with wider browser support.