The purpose of this library is to help users building heavily customized, pure-HTML5 JavaScript file uploaders with ease.
- Works well with Browserify, but standalone builds are provided, so you can use it with loaders like AMD or globally (see below)
- Event-based (using the only one dependency, EventEmitter3)
- Can be attached to classic input tags or divs (to do Drag & Drop upload)
- No jQuery (or whatever) dependencies
Install with npm:
npm install html5-uploader
Then, simply require this package:
var Uploader = require('html5-uploader');
var uploader = new Uploader({
el: '#uploader',
...
});Use the standalone build:
<html>
<head>
...
</head>
<body>
...
<div id="uploader"></div>
<script src="html5-uploader.min.js"></script>
<script type="text/javascript">
var uploader = new Uploader({
el: '#uploader',
...
});
...
</script>
</body>
</html>It's very straighforward. Have a look at this great blog post about using Browserify standalone builds.
I strongly recommend to clone this repo and launch the examples server. Simply run npm dev task:
npm run dev
Then open http://localhost:3000 and take a look at the code on /examples folder.
Alternatively, you can view them on http://mpangrazzi.github.io (note that upload is disabled, and source code is already browserified).
Fired when one or more files are added to Uploader instance.
You can also have access to underlying FormData object here, which already contains your file. So, you can easily append other fields, if you want.
uploader.on('files:added', function(files) {
/**
* Here you have files, so you can perform validations, UI changes, ...
*/
/**
* Appending a sample field to underlying FormData object
*/
this.formData.append('sample', 'test');
});Fired once for every file added.
If the file matches image/* mime type it's readed using FileReader API and $img (a DOM image element) is provided on event handler.
uploader.on('file:preview', function(file, $img) {
/**
* Here you can populate a preview template with `file` or `$img`.
* For example:
*/
if ($img) {
var $preview = document.getElementById('#preview');
div.appendChild($img);
}
});Fired when .clearFiles() public method is called.
uploader.on('files:cleared', function() {
/**
* Here you may clear your #preview element
*/
});If upload progress support is available in XMLHttpRequest, then this event is fired every time progress changes.
uploader.on('upload:progress', function(progress) {
/**
* `progress` is a float Number between 0.0 and 100.0.
*
* Here you can, for example, increment a progress bar.
*
* You can format the number using `Math.floor(progress)`, `progress.toFixed(2)` etc.
*/
});Fired when files upload is done.
uploader.on('upload:done', function(response) {
/**
* `response` is the server response, returned as a String
*
* Here you can, for example, notify the user.
*/
});Fired when an error occurs (e.g. upload failed). I strongly recommend to add a listener on this event.
uploader.on('error', function(err) {
/**
* `err` is an Error instance.
*
* If there's an error during upload, `err` will also have a `status`
* property containing the HTTP status code received from server
*/
if (err.status) console.error(err.status);
console.error(err.message);
});If you have attached Uploader to a <div>, you can listen to those events to do some fancy UI changes.
To launch tests, simply run:
npm test
Then open http://localhost:3000 to see the report.
var uploader = new Uploader({ ... });Uploader available options are:
el: required. Can be a DOM reference or a CSS selector. Supported tags are<input type="file">(classic file input) or a<div>(for drag & drop).name: Name of the FormData param used for upload. Default:file.url: URL of your server-side upload API endpoint. If omitted, calling upload() will throw or emit and error.method: Request method used during upload. Default:POST.headers: An optional object with headers to be set on the XHR object before sending, e.g.{'X-CSRFToken': token}
Upload all the files to specified endpoint, using HTML5 FormData.
Be sure to have a listener on upload:progress, upload:done and error events before calling this method.
Returns a FileList with current files.
Clear current files.
Be sure to install dev dependencies using npm install. Browserify and npm scripts are used for build system.
npm run buildwill build a standalone, non-minified versionnpm run build-minwill build a standalone, minified version
Also:
npm run devis useful for development. Launch an examples server, watch for changes, and automatically rebuild all if needed.
It will work where File and FileReader API are supported.
- Chrome 7+
- Firefox 4+
- IE 10+
- Opera 12+
- Safari 6+
You can find more info about API support on caniuse.com.