DropzoneJS - Drag&drop file uploads with image previews

DropzoneJS is an open source library that provides drag and drop file uploads with image previews and shows nice progress bars.

Browser support

• Chrome 7+
• Firefox 4+
• IE 10+
• Opera 12+ (Version 12 for MacOS is disabled because their API is buggy)
• Safari 6+

Source: dropzonejs.com

1. INSTALLATION

<script src="./path/to/dropzone.js"></script>

2. USAGE

The typical way of using dropzone is by creating a form element with the class dropzone:

<form action="/file-upload"
      class="dropzone"
      id="my-awesome-dropzone"></form>

That's it. Dropzone will find all form elements with the class dropzone, automatically attach itself to it, and upload files dropped into it to the specified action attribute. The uploaded files can be handled just as if there would have been a html input like this:

<input type="file" name="file" />

If you want your file uploads to work even without JavaScript, you can include an element with the classfallback that dropzone will remove if the browser is supported. If the browser isn't supported, Dropzone will not create fallback elements if there is a fallback element already provided. (Obviously, if the browser doesn't support JavaScript, the form will stay as is)

Typically this will look like this:

<form action="/file-upload" class="dropzone">
  <div class="fallback">
    <input name="file" type="file" multiple />
  </div>
</form>

Create dropzones programmatically

Alternatively you can create dropzones programmaticaly (even on non form elements) by instantiating theDropzone class

// Dropzone class:
var myDropzone = new Dropzone("div#myId", { url: "/file/post"});

or if you use jQuery, you can use the jQuery plugin Dropzone ships with:

// jQuery
$("div#myId").dropzone({ url: "/file/post" });

3. OPTIONS

There are two ways to configure dropzones.

The obvious way is to pass an options object when instantiating a dropzone programmatically like in the previous create dropzones programmatically section.

But if you just have HTML elements with the dropzone class, then you don't programmatically instantiate the objects, so you have to store the configuration somewhere so Dropzone knows how to configure the dropzones when instantiating them.

This is done with the Dropzone.options object.

// "myAwesomeDropzone" is the camelized version of the HTML element's ID
Dropzone.options.myAwesomeDropzone = {
  paramName: "file", // The name that will be used to transfer the file
  maxFilesize: 2, // MB
  accept: function(file, done) {
    if (file.name == "justinbieber.jpg") {
      done("Naha, you don't.");
    }
    else { done(); }
  }
};

If you want to disable the auto discover behaviour of Dropzone, you can either disable it on a per element basis, or in general:

// Prevent Dropzone from auto discovering this element:
Dropzone.options.myAwesomeDropzone = false;
// This is useful when you want to create the
// Dropzone programmatically later

// Disable auto discover for all elements:
Dropzone.autoDiscover = false;

The valid options are:

to translate dropzone, you can also provide these options:

4. EVENTS

Dropzone triggers events when processing files, to which you can register easily.

Example:

// The recommended way from within the init configuration:
Dropzone.options.myAwesomeDropzone = {
  init: function() {
    this.on("addedfile", function(file) { alert("Added file."); });
  }
};

// Or programmatically, when creating a Dropzone.
// This is more complex and should only be used if you need to create your
// Dropzones on demand.
//
// This example uses jQuery so it creates the Dropzone, only when the DOM has
// loaded.

// Disabling autoDiscover, otherwise Dropzone will try to attach twice.
Dropzone.autoDiscover = false;
// or disable for specific dropzone:
// Dropzone.options.myDropzone = false;

$(function() {
  // Now that the DOM is fully loaded, create the dropzone, and setup the
  // event listeners

  var myDropzone = new Dropzone("#my-dropzone");

  myDropzone.on("addedfile", function(file) {
    /* Maybe display some more file information on your page */
  });

})

Available events:

All of these receive the event as first parameter:

All of these receive the file as the first parameter:

All of these receive a list of files as first parameter and are only called if the uploadMultiple option is true:

Special events:

5. METHODS

If you want to remove an added file from the dropzone, you can call .removeFile(file). This method also triggers the removedfile event.

Here's an example that would automatically remove a file when it's finished uploading:

myDropzone.on("complete", function(file) {
  myDropzone.removeFile(file);
});

If you want to remove all files, simply use .removeAllFiles(). Files that are in the process of being uploaded won't be removed. If you want files that are currently uploading to be canceled, call.removeAllFiles(true) which will cancel the uploads.

If you have autoProcessQueue disabled, you'll need to call .processQueue() yourself.

This can be useful if you want to display the files and let the user click an accept button to actually upload the file(s).

To access all files in the dropzone, use myDropzone.files.

To get

• all accepted files: .getAcceptedFiles()
• all rejected files: .getRejectedFiles()
• all queued files: .getQueuedFiles()
• all uploading files: .getUploadingFiles()

If you do not need a dropzone anymore, just call .disable() on the object. This will remove all event listeners on the element, and clear all file arrays. To reenable a Dropzone use .enable().

If you don't like the default browser modals for confirm calls, you can handle them yourself by overwriting Dropzone.confirm.

Dropzone.confirm = function(question, accepted, rejected) {
  // Ask the question, and call accepted() or rejected() accordingly.
  // CAREFUL: rejected might not be defined. Do nothing in that case.
};

6. LAYOUT

The HTML that is generated for each file by dropzone is defined with the option previewTemplatewhich defaults to this:

<div class="dz-preview dz-file-preview">
  <div class="dz-details">
    <div class="dz-filename"><span data-dz-name></span></div>
    <div class="dz-size" data-dz-size></div>
    <img data-dz-thumbnail />
  </div>
  <div class="dz-progress"><span class="dz-upload" data-dz-uploadprogress></span></div>
  <div class="dz-success-mark"><span>✔</span></div>
  <div class="dz-error-mark"><span>✘</span></div>
  <div class="dz-error-message"><span data-dz-errormessage></span></div>
</div>

The container (dz-preview) gets the dz-processing class when the file gets processed, dz-success when the file got uploaded and dz-error in case the file couldn't be uploaded. In the latter case, [data-dz-errormessage] will contain the text returned by the server.

You can access the HTML of the file preview in any of the events with file.previewElement.

If you decide to rewrite the previewTemplate from scratch, you should put elements with the data-dz-* attributes inside:

• data-dz-name
• data-dz-size
• data-dz-thumbnail (This has to be an <img /> element and the alt and src attributes will be changed by Dropzone)
• data-dz-uploadprogress (Dropzone will change the style.width property from 0% to100% whenever there's a uploadprogress event)
• data-dz-errormessage

The default options for Dropzone will look for those element and update the content for it.

If you want some specific link to remove a file (instead of the built in addRemoveLinks option), you can simply insert elements in the template with the data-dz-remove attribute. Example:

  <img src="removebutton.png" alt="Click me to remove the file." data-dz-remove />

You are not forced to use those conventions though. If you override all the default event listeners you can completely rebuild your layout from scratch.

See the installation section on how to add the stylesheet and spritemaps if you want your dropzone to look like the one on this page.