Skip to content

FAQ

Jump to bottom
Matias Meno edited this page Jul 27, 2020 · 41 revisions

I try to keep this FAQ as complete as possible. If you think that there is something missing, please contact me.

I get the error "Dropzone already attached." when creating the Dropzone.

This is most likely due to the autoDiscover feature of Dropzone.

When Dropzone starts, it scans the whole document, and looks for elements with the dropzone class. It then creates an instance of Dropzone for every element found. If you, later on, create a Dropzone instance yourself, you'll create a second Dropzone which causes this error.

So you can either:

  1. Turn off autoDiscover globally like this: Dropzone.autoDiscover = false;, or
  2. Turn off autoDiscover of specific elements like this: Dropzone.options.myAwesomeDropzone = false;

You don't have to create an instance of Dropzone programmatically in most situations! It's recommended to leave autoDiscover enabled, and configure your Dropzone in the init option of your configuration.

Why are large files not uploading?

There is a maxFilesize option in Dropzone which defaults to 256 (MB). Increase this to upload files bigger than that. If your files upload fine but aren't stored on the server, then it's due to your server configuration. Most servers limit the file upload size as well. Please check with the appropriate documentation.

Why are some image thumbnails not generated?

There is a maxThumbnailFilesize option in Dropzone which defaults to 10 (MB) to prevent the browser from downsizing images that are too big. Increase this to create thumbnails of bigger files.

How to get notified when all files finished uploading?

At the moment there isn't a single event to do that, but you can listen to the complete event, which fires every time a file completed uploading, and see if there are still files in the queue or being processed.

There is a queuecomplete event now that fires when all files in the queue have been uploaded.

How to show an error returned by the server?

Very often you have to do some verification on the server to check if the file is actually valid. If you want Dropzone to display any error encountered on the server, all you have to do, is send back a proper HTTP status code in the range of 400 - 500.

In most frameworks those error codes are generated automatically when you send back an error to the client. In PHP (for example) you can set it with the header command.

Dropzone will then know that the file upload was invalid, and will display the returned text as error message.

If the Content-Type of your response is text/plain, you can just return the text without any further markup. If the Content-Type is application/json, Dropzone will use the error property of the provided object. Eg.: { "error": "File could not be saved." }

How to add a button to remove each file preview?

Starting with Dropzone version 3.5.0, there is an option that will handle all this for you: addRemoveLinks. This will add an <a class="dz-remove">Remove file</a> element to the file preview that will remove the file, and it will change to Cancel upload if the file is currently being uploaded (this will trigger a confirmation dialog).

You can change those sentences with the dictRemoveFile, dictCancelUpload and dictCancelUploadConfirmation options.

If you still want to create the button yourself, you can do so like this:

<form action="/target-url" id="my-dropzone" class="dropzone"></form>

<script>
  // myDropzone is the configuration for the element that has an id attribute
  // with the value my-dropzone (or myDropzone)
  Dropzone.options.myDropzone = {
    init: function() {
      this.on("addedfile", function(file) {

        // Create the remove button
        var removeButton = Dropzone.createElement("<button>Remove file</button>");
        

        // Capture the Dropzone instance as closure.
        var _this = this;

        // Listen to the click event
        removeButton.addEventListener("click", function(e) {
          // Make sure the button click doesn't submit the form:
          e.preventDefault();
          e.stopPropagation();

          // Remove the file preview.
          _this.removeFile(file);
          // If you want to the delete the file on the server as well,
          // you can do the AJAX request here.
        });

        // Add the button to the file preview element.
        file.previewElement.appendChild(removeButton);
      });
    }
  };
</script>

How to submit additional data along the file upload?

If your Dropzone element is a <form> element, all hidden input fields will automatically be submitted as POST data along with the file upload.

Example:

<form action="/" class="dropzone">
  <input type="hidden" name="additionaldata" value="1" />

  <!-- If you want control over the fallback form, just add it here: -->
  <div class="fallback"> <!-- This div will be removed if the fallback is not necessary -->
    <input type="file" name="youfilename" />
    etc...
  </div>
</form>

I want to display additional information after a file uploaded.

To use the information sent back from the server, use the success event, like this:

Dropzone.options.myDropzone = {
  init: function() {
    this.on("success", function(file, responseText) {
      // Handle the responseText here. For example, add the text to the preview element:
      file.previewTemplate.appendChild(document.createTextNode(responseText));
    });
  }
};

How to show an image created by the server after upload

If your server generates an image (for example, you render a PDF on the server after upload), you can display that image easily once it uploads like this:

Let's say your server responds with JSON like this:

{ "imageUrl": "http://my.image/file.jpg" }
Dropzone.options.myDropzone = {
  init: function() {
    this.on("success", function(file, serverResponse) {
      // Called after the file successfully uploaded.

      // If the image is already a thumbnail:
      this.emit('thumbnail', file, serverResponse.imageUrl);

      // If it needs resizing:
      this.createThumbnailFromUrl(file, serverResponse.imageUrl);
    });
  }
};

How to show files already stored on server

Dropzone.options.myDropzone = {
  init: function() {
    let myDropzone = this;

    // If you only have access to the original image sizes on your server,
    // and want to resize them in the browser:
    let mockFile = { name: "Filename 2", size: 12345 };
    myDropzone.displayExistingFile(mockFile, "https://i.picsum.photos/id/959/600/600.jpg");

    // If the thumbnail is already in the right size on your server:
    let mockFile = { name: "Filename", size: 12345 };
    let callback = null; // Optional callback when it's done
    let crossOrigin = null; // Added to the `img` tag for crossOrigin handling
    let resizeThumbnail = false; // Tells Dropzone whether it should resize the image first
    myDropzone.displayExistingFile(mockFile, "https://i.picsum.photos/id/959/120/120.jpg", callback, crossOrigin, resizeThumbnail);

    // If you use the maxFiles option, make sure you adjust it to the
    // correct amount:
    let fileCountOnServer = 2; // The number of files already uploaded
    myDropzone.options.maxFiles = myDropzone.options.maxFiles - fileCountOnServer;
  }
};

Use own confirm implementation

If you are unhappy with the way Dropzone asks a user if she wants to cancel or remove a file, and want to use some other way (e.g.: bootstrap's modal), you can simply overwrite the Dropzone.confirm function.

// accepted and rejected are functions to be called whenever the user response
// has been received.
// rejected is not mandatory! So make sure to check if it exists before
// calling it. Do nothing if it doesn't.
Dropzone.confirm = function(question, accepted, rejected) {
  // Do your thing, ask the user for confirmation or rejection, and call
  // accepted() if the user accepts, or rejected() otherwise. Make
  // sure that rejected is actually defined!
};

How can I limit the number of files

You're in luck! Starting with 3.7.0 Dropzone supports the maxFiles option. Simply set it to the desired quantity and you're good to go. If you don't want the rejected files to be viewed, simply register for the maxfilesexceeded event, and remove the file immediately:

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

Provide a thumbnail for files

If you want to provide a thumbnail for files other than images, you can, by emitting the thumbnail event yourself.

myDropzone.on("addedfile", function(file) {
  if (!file.type.match(/image.*/)) {
    // This is not an image, so Dropzone doesn't create a thumbnail.
    // Set a default thumbnail:
    myDropzone.emit("thumbnail", file, "http://path/to/image");

    // You could of course generate another image yourself here,
    // and set it as a data url.
  }
});

Reject images based on image dimensions

This is a bit tricky. The "problem" is, that the image dimensions are only known after the thumbnail event fired, which could potentially happen after the file already uploaded since thumbnail creation is queued.
That's why the accept function (which determines if the file should be rejected) is called before the dimensions are actually known. Fortunately the accept function is asynchronous, and can "wait" for the thumbnail event. This is why you need to put the accept callback in the file object so you can reference it after the thumbnail has been generated:

var maxImageWidth = 800,
    maxImageHeight = 800;

Dropzone.options.myDropzone = {

  // Make sure only images are accepted
  acceptedFiles: "image/*",

  init: function() {
    // Register for the thumbnail callback.
    // When the thumbnail is created the image dimensions are set.
    this.on("thumbnail", function(file) {
      // Do the dimension checks you want to do
      if (file.width > maxImageWidth || file.height > maxImageHeight) {
        file.rejectDimensions()
      }
      else {
        file.acceptDimensions();
      }
    });
  },

  // Instead of directly accepting / rejecting the file, setup two
  // functions on the file that can be called later to accept / reject
  // the file.
  accept: function(file, done) {
    file.acceptDimensions = done;
    file.rejectDimensions = function() { done("Invalid dimension."); };
    // Of course you could also just put the `done` function in the file
    // and call it either with or without error in the `thumbnail` event
    // callback, but I think that this is cleaner.
  }
};

Chunked uploads

Dropzone offers the possibility to upload files in chunks. The relevant configuration options for this feature are:

  • chunking which should be set to true
  • forceChunking, if true, will always send a file in chunks, even if it is only one chunk
  • chunkSize in bytes
  • parallelChunkUploads, if true, the chunks will be uploaded simultaneously
  • retryChunks, if true, the library will retry to upload a chunk if it fails
  • retryChunksLimit defaults to 3

Then there are two important callbacks. The first one is: params which can be a function, that receives files, xhr and chunk as the first argument. If chunking is enabled, you know that files only contains that one file, and chunk is the object holding all the information about the current chunk. Example:

var chunk = {
  file: file,
  index: 0,
  status: Dropzone.UPLOADING,
  progress: 0.4
}

See the documentation for that parameter for more information or look at the source code for the default implementation.

The second important callback is chunksUploaded, which gets the file that finished uploading and the done function as second argument. Do whatever you need to do in that function, to tell the server that the file finished uploading and invoke the done() function when ready.

Clone this wiki locally