# Introduction

The documentation for the JavaScript library Dropzone.

Dropzone is a simple JavaScript library that helps you add file drag and drop functionality to your web forms. It is one of the most popular drag and drop library on the web and is used by millions of people.

There are *many* configuration options, so Dropzone can be used in a variety of situations.

Some of Dropzone's highlights are:

* Beautiful by default.
* Image thumbnail previews. Simply register the callback `thumbnail(file, data)`

  and display the image wherever you like
* Progress Bars
* Retina enabled
* Multiple files and synchronous uploads
* Support for large files
* Chunked uploads (single files can be uploaded as chunks in multiple HTTP requests)
* Complete theming. The look and feel of Dropzone is just the default theme. You

  can define everything yourself by overwriting the default event listeners.
* Browser image resizing (resize the images before you upload them to your

  server)
* Well tested


# Installation

There are two ways to add Dropzone to your projects. If you are using a package manager please refer to the [npm or yarn](/getting-started/installation/npm-or-yarn)section. If you simply want to use Dropzone without any bundler or package manager, please refer to the [Stand-alone file](/getting-started/installation/stand-alone)section.

{% hint style="info" %}
Dropzone.js does not handle your file uploads on the **server**. You have to implement the code to receive and store the file yourself. See the section [Server side implementation](/getting-started/setup/server-side-implementation) for more information.

If you're looking for an out-of-the-box solution, consider using [**Dropzone Plus**](https://www.dropzone.dev/plus).
{% endhint %}


# npm or yarn

This is how I use the library myself

As with most visual JavaScript libraries there are two sides to the story: getting the JavaScript code in your project, and getting the CSS code. Let's start with JS.

Add dropzone as a dependency to your project:

{% tabs %}
{% tab title="npm" %}

```bash
$ npm install --save dropzone
```

{% endtab %}

{% tab title="yarn" %}

```bash
$ yarn add dropzone
```

{% endtab %}
{% endtabs %}

In your html, make sure you have an element that will act as the dropzone:

```markup
<!-- Example of a form that Dropzone can take over -->
<form action="/target" class="dropzone"></form>
```

## JavaScript

Without going too much into detail, historically, there have been plenty of ways to import libraries in JavaScript. Fortunately, not too long ago a standard was introduced that was implemented in browsers as well. This standard is called [ECMAScript modules](https://nodejs.org/api/esm.html), also commonly referred to as [JavaScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules). This has caused JavaScript modules to become a defacto standard, which is why I recommend to use this approach.

Before JavaScript modules there were quite a few other standards. The only other module standard that Dropzone now supports is the [CommonJS format](https://en.wikipedia.org/wiki/CommonJS) which is what node is using too (note that [node also has support for JavaScript modules](https://nodejs.medium.com/announcing-core-node-js-support-for-ecmascript-modules-c5d6dc29b663) now).

We also provide a standalone file that you can simply include in your browser. See the corresponding section for this: [Stand-alone file](/getting-started/installation/stand-alone).

```javascript
// If you are using JavaScript/ECMAScript modules:
import Dropzone from "dropzone";

// If you are using CommonJS modules:
const { Dropzone } = require("dropzone");

// If you are using an older version than Dropzone 6.0.0,
// then you need to disabled the autoDiscover behaviour here:
Dropzone.autoDiscover = false;

let myDropzone = new Dropzone("#my-form");
myDropzone.on("addedfile", file => {
  console.log(`File added: ${file.name}`);
});
```

{% hint style="warning" %}
In order for Dropzone to find the `#my-form` the element must already exist. Either put your `<script>` import at the end of your HTML file, or use some sort of `window.onload` logic.
{% endhint %}

## CSS

Dropzone ships with two files: a `basic.css` and a `dropzone.css`. The `dropzone.css` contains all the styling you can see in the examples and is a ready-to-go solution. If you want to have total control over the styling, you can use the `basic.css` as a base, and build on top of that, or not use any of the provided CSS files at all.

Importing this CSS file greatly depends on the bundler or framework that you are using so I won't go into much detail here.

You can also simply include the CSS file in your html. Refer to the [Stand-alone file](/getting-started/installation/stand-alone)section for this.

{% hint style="info" %}
You can check out the [examples repository](https://github.com/dropzone/dropzone-examples) for ways to handle this with different bundlers.
{% endhint %}


# Composer

The PHP dependency manager

Dropzone is published to [packagist](https://packagist.org/packages/enyo/dropzone) and compatible with composer. Use it as you would any other package.


# Stand-alone file

Simply download the files

I don't recommend this option, because it is hard to maintain, but sometimes you just have a small project that you don't want to spend any unnecessary time on, and using the stand-alone `.js` files is fine for you.

Instead of having to download the files yourself, you can directly link to the unpkg host like this:

```html
<script src="https://unpkg.com/dropzone@5/dist/min/dropzone.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/dropzone@5/dist/min/dropzone.min.css" type="text/css" />
```

Dropzone is now active and available as `window.Dropzone`.

{% hint style="info" %}
Note that the imported css file is optional.&#x20;
{% endhint %}

### Dropzone v6

Dropzone has dropped Internet Explorer support in version 6, which is still in beta this point. If you already want to use a much lighter script (46kB vs 115kB) and don't care about Internet Explorer support, you can already opt into it like this:

```html
<script src="https://unpkg.com/dropzone@6.0.0-beta.1/dist/dropzone-min.js"></script>
<link href="https://unpkg.com/dropzone@6.0.0-beta.1/dist/dropzone.css" rel="stylesheet" type="text/css" />
```

If you do, please make sure to check the [CHANGELOG](https://github.com/dropzone/dropzone/blob/main/CHANGELOG.md) to make sure the breaking changes don't affect you.


# Setup

How to setup a Dropzone on your website.

After you've [installed Dropzone](/getting-started/installation) there are two ways to setup Dropzone. The easiest way is to let Dropzone auto discover your forms, and attach the drag and drop events automatically. For that, you simply need to provide a class to your form. This is called the **declarative** setup.

{% content-ref url="/pages/-MOvb9N5cMt-2OZ3O0U5" %}
[Declarative](/getting-started/setup/declarative)
{% endcontent-ref %}

If you have a more complex use case, or you'd like to control *when* the Dropzone object is created and listens to events, you can instantiate the Dropzone yourself. This is called the **imperative** setup.

{% content-ref url="/pages/-MOvuFkyOZDEavDwLTRG" %}
[Imperative](/getting-started/setup/imperative)
{% endcontent-ref %}

### Which approach is better?

There is not one approach that is better than the other. I would say that if you use a package manager, it's likely you'll prefer the **imperative** approach, but the **declarative** approach is generally a bit simpler.

Choose the **declarative** approach when...

* ...you're not used to writing JavaScript code
* ...your configuration is very simple or you're happy with the defaults

Choose the **imperative** approach when...

* ...you're writing a web app, and your routes need to create the Dropzone after loading the page
* ...you only want to create a Dropzone after specific events (for example if the user expanded a section)
* ...the configuration of your Dropzone depends on some additional context (for example if you want to send the files to a different URL on some other condition)
* ...you simply prefer the imperative way.


# Declarative

How to create a Dropzone upload with HTML attributes.

The easiest way to use dropzone is by creating a form element with the class `dropzone`:

```markup
<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:

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

{% hint style="info" %}
If you want another name than `file` you can [configure Dropzone](/configuration/basics) with the option `paramName`.
{% endhint %}

## Configuration

When declaring a Dropzone like this, you might be wondering how to configure it then, and fortunately it's quite easy:

1. Give the element that you want to configure an html `id`
2. Setup the configuration on `Dropzone.options`

#### Example:

```markup
<script>
  // Note that the name "myDropzone" is the camelized
  // id of the form.
  Dropzone.options.myDropzone = {
    // Configuration options go here
  };
</script>
<form action="/target" class="dropzone" id="my-dropzone"></form>
```

You can create as many options on Dropzone.options as you need — for each HTML element that you created, you can simply add the configuration.

For information on available configuration options, see the [configuration section](/configuration/basics).

### The "auto discover" feature

{% hint style="danger" %}
The auto discover feature has been removed in Dropzone version 6.0.0! If you depend on this you can simply add this code to the end of your document:

```html
<script>
  Dropzone.discover();
</script>
```

{% endhint %}

The way this works is called "auto discover". Dropzone checks when the DOM content finished loading, and then parses all HTML elements and looks for one with the class `dropzone`. If it finds an element, it checks if the element has an `id`. If it does, then it converst the id name to camel case (`my-dropzone` -> `myDropzone`) and checks if there is an entry in `Dropzone.options` with that key. If there is, then it uses that configuration object to instantiate the Dropzone for this object.

This behaviour can be disabled in two ways:

1. Either set `Dropzone.autoDiscover = false;` somewhere in your JS. Just make sure it's invoked before the DOM ready event is dispatched.
2. Set `Dropzone.options.myDropzone = false;` for individual dropzones. This allows you to use the auto discover feature, and only disable it for specific elements.

{% hint style="warning" %}
Dropzone parses the document when the document has finished loading, looks for elements that have the `dropzone` class, checks if there is a configuration in `Dropzone.options` for it, and then creates a Dropzone instance for that element. If all of that happened, before you defined your configuration, then **Dropzone will miss the configuration**. So make sure, that your **configuration** code is **reached before** Dropzone **auto discovers** these elements.
{% endhint %}

If you're not too keen on this approach, don't worry. Go to the next section to see how to create them imperatively.


# Imperative

How to create a Dropzone upload with JavaScript.

As an alternative to the declarative way, you can create Dropzones imperatively (even on non `<form>`elements) by instantiating the `Dropzone` class:

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
// The constructor of Dropzone accepts two arguments:
//
// 1. The selector for the HTML element that you want to add
//    Dropzone to, the second
// 2. An (optional) object with the configuration
let myDropzone = new Dropzone("div#myId", { url: "/file/post"});
```

{% endtab %}

{% tab title="jQuery" %}

```javascript
// The dropzone method is added to jQuery elements and can
// be invoked with an (optional) configuration object.
$("div#myId").dropzone({ url: "/file/post" });
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Don’t forget to specify an `url` option if you’re not using a `<form>` element, since Dropzone doesn’t know where to post to without an action attribute. On form elements, Dropzone defaults to the `action` attribute.
{% endhint %}

For a list of all configuration options, refer to the [configuration section](/configuration/basics).


# Server Side Implementation

How to handle uploaded files on the server.

Dropzone does **not** provide the server side implementation of handling the files.

The way files are uploaded is identical to a standard file upload with a standard HTML form like this:

```markup
<form action="" method="post" enctype="multipart/form-data">
  <input type="file" name="file" />
</form>
```

So if your server accepts files, uploaded like this, it will accept files uploaded with Dropzone.

So please look at the corresponding documentation of the server implementation you're using. Here are a few documentations, if you think I should add some, please contact me.

* [Spring](https://spring.io/guides/gs/uploading-files/)
* [NodeJS with express](http://howtonode.org/really-simple-file-uploads)
* [Ruby on rails](http://guides.rubyonrails.org/form_helpers.html#uploading-files)
* [Complete PHP tutorial](http://www.startutorial.com/articles/view/how-to-build-a-file-upload-form-using-dropzonejs-and-php) by startutorial.com
* [Basic PHP file upload](http://www.php.net/manual/en/features.file-upload.post-method.php#example-354)
* [Tutorial for Dropzone and Lavarel (PHP)](http://maxoffsky.com/code-blog/howto-ajax-multiple-file-upload-in-laravel/) written by Maksim Surguy
* [Symfony2 and Amazon S3](http://www.jesuisundev.fr/upload-drag-drop-via-dropzonejs-symfony2-on-cloud-amazon-s3/)
* [File upload in ASP.NET MVC using Dropzone JS and HTML5](http://venkatbaggu.com/file-upload-in-asp-net-mvc-using-dropzone-js-and-html5/)
* [Servicestack and Dropzone](http://www.buildclassifieds.com/2016/01/08/uploading-images-servicestack-and-dropzone/)
* [How to build a file upload form using DropzoneJS and Go](https://hackernoon.com/how-to-build-a-file-upload-form-using-dropzonejs-and-go-8fb9f258a991)
* [How to display existing files on server using DropzoneJS and Go](https://hackernoon.com/how-to-display-existing-files-on-server-using-dropzonejs-and-go-53e24b57ba19)

Paid documentations:

* [eBook for Dropzone with PHP](http://www.startutorial.com/homes/dropzonejs_php_the_complete_guide?utm_source=dzj\&utm_medium=banner\&utm_campaign=dropzonejs) by startutorial.com.

Please look at the [Dropzone FAQ](https://gitlab.com/meno/dropzone/-/wikis/FAQ) if you need more information.


# Fallback for no JavaScript

In case you want to handle browsers that don't have JavaScript enabled.

Sometimes you need to build websites that should work even if the user doesn't have JavaScript enabled or the browser is not supported. Of course, a drag'n'drop JavaScript library won't work in these cases, but Dropzone got you covered by offering a way to define a fallback.

Inside your dropzone HTML element (in most cases that's a `<form>` element), you can define an additional element with the class `fallback` . When (or in this case: "if") Dropzone initializes, it will simply remove this element.

Here is an example of what this might look like:

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

So in case the browser doesn't support JavaSript, the user will simply see the `fallback` div with the file input element, and everything will work normally but with no drag and drop support.

*If* the browser is supported however, this element will be removed, and Dropzone will add a notice that it accepts dropped files and handle them.


# Basics

In this section we'll co over the fundamentals of configuring Dropzones.

{% hint style="info" %}
You should already be familiar on how to pass a configuration object to Dropzone in the [declarative](/getting-started/setup/declarative) and the [imperative](/getting-started/setup/imperative) way. If not, please visit the respective sections.
{% endhint %}

This is what a typical configuration of Dropzone would look like:

{% tabs %}
{% tab title="Declarative" %}

```markup
<form action="/target" class="dropzone" id="my-great-dropzone"></form>

<script>
  Dropzone.options.myGreatDropzone = { // camelized version of the `id`
    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(); }
    }
  };
</script>
```

{% endtab %}

{% tab title="Imperative" %}

```javascript
import Dropzone from "dropzone";

let myDropzone = Dropzone({
  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(); }
  }
});
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
For a list of all possible options, refer to the [`src/options.js`](https://github.com/dropzone/dropzone/blob/main/src/options.js) file.
{% endhint %}

### Events

If you want to react to events happening (a file has been added or removed, an upload started, a progress changed, etc...) you want to be listening to events. Checkout the events section for more information on events.

{% content-ref url="/pages/-MOvpvJ\_cUjweqgEXfAI" %}
[Events](/configuration/events)
{% endcontent-ref %}

### Overriding default event handlers

{% hint style="danger" %}
In general **you should never have to do this**, and you should be familiar with the code if you decide to do it.
{% endhint %}

You can also override default event handlers. This should be approached with absolute caution since it can break if you upgrade the library and can also remove default functionality that you might not want to  lose:

```javascript
let myDropzone = Dropzone("#my-element", {
  addedfile: file => {
    // ONLY DO THIS IF YOU KNOW WHAT YOU'RE DOING!
  }
});
```

The difference here, is that the default event handler `addedfile` has been changed, instead of adding a new event handler with `myDropzone.on("addedfile", () => {})`


# Configuration Options

Here is a list of all available options for Dropzone. In case any of this information is outdated (please inform us, if that's the case) or you need more insight, you can always look at the [options.js](https://github.com/dropzone/dropzone/blob/main/src/options.js) that is used in the actual library.

| Name                    | Default     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`                   | `null`      | Has to be specified on elements other than form (or when the form doesn't have an `action` attribute). You can also provide a function that will be called with `files` and must return the url (since `v3.12.0`)                                                                                                                                                                                                                                                 |
| `method`                | `"post"`    | Can be changed to `"put"` if necessary. You can also provide a function that will be called with `files` and must return the method (since `v3.12.0`).                                                                                                                                                                                                                                                                                                            |
| `withCredentials`       | `false`     | Will be set on the XHRequest.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `timeout`               | `null`      | The timeout for the XHR requests in milliseconds (since `v4.4.0`). If set to null or 0, no timeout is going to be set.                                                                                                                                                                                                                                                                                                                                            |
| `parallelUploads`       | `2`         | How many file uploads to process in parallel (See the Enqueuing file uploads documentation section for more info)                                                                                                                                                                                                                                                                                                                                                 |
| `uploadMultiple`        | `false`     | Whether to send multiple files in one request. If this it set to true, then the fallback file input element will have the `multiple` attribute as well. This option will also trigger additional events (like `processingmultiple`). See the events documentation section for more information.                                                                                                                                                                   |
| `chunking`              | `false`     | <p>Whether you want files to be uploaded in chunks to your server. This can't be used in combination with <code>uploadMultiple</code>.<br>See [chunksUploaded](#config-chunksUploaded) for the callback to finalise an upload.</p>                                                                                                                                                                                                                                |
| `forceChunking`         | `false`     | If `chunking` is enabled, this defines whether \*\*every\*\* file should be chunked, even if the file size is below chunkSize. This means, that the additional chunk form data will be submitted and the `chunksUploaded` callback will be invoked.                                                                                                                                                                                                               |
| `chunkSize`             | `2000000`   | If `chunking` is `true`, then this defines the chunk size in bytes.                                                                                                                                                                                                                                                                                                                                                                                               |
| `parallelChunkUploads`  | `false`     | If `true`, the individual chunks of a file are being uploaded simultaneously.                                                                                                                                                                                                                                                                                                                                                                                     |
| `retryChunks`           | `false`     | Whether a chunk should be retried if it fails.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `retryChunksLimit`      | `3`         | If `retryChunks` is true, how many times should it be retried.                                                                                                                                                                                                                                                                                                                                                                                                    |
| `maxFilesize`           | `256`       | The maximum filesize (in bytes) that is allowed to be uploaded.                                                                                                                                                                                                                                                                                                                                                                                                   |
| `paramName`             | `"file"`    | The name of the file param that gets transferred. \*\*NOTE\*\*: If you have the option `uploadMultiple` set to `true`, then Dropzone will append `[]` to the name.                                                                                                                                                                                                                                                                                                |
| `createImageThumbnails` | `true`      | Whether thumbnails for images should be generated                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `maxThumbnailFilesize`  | `10`        | In MB. When the filename exceeds this limit, the thumbnail will not be generated.                                                                                                                                                                                                                                                                                                                                                                                 |
| `thumbnailWidth`        | `120`       | If `null`, the ratio of the image will be used to calculate it.                                                                                                                                                                                                                                                                                                                                                                                                   |
| `thumbnailHeight`       | `120`       | The same as `thumbnailWidth`. If both are null, images will not be resized.                                                                                                                                                                                                                                                                                                                                                                                       |
| `thumbnailMethod`       | `"crop"`    | How the images should be scaled down in case both, `thumbnailWidth` and `thumbnailHeight` are provided. Can be either `contain` or `crop`.                                                                                                                                                                                                                                                                                                                        |
| `resizeWidth`           | `null`      | <p>If set, images will be resized to these dimensions before being **uploaded**. If only one, <code>resizeWidth</code> **or** <code>resizeHeight</code> is provided, the original aspect ratio of the file will be preserved.<br>The <code>options.transformFile</code> function uses these options, so if the <code>transformFile</code> function is overridden, these options don't do anything.</p>                                                            |
| `resizeHeight`          | `null`      | See `resizeWidth`.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `resizeMimeType`        | `null`      | The mime type of the resized image (before it gets uploaded to the server). If `null` the original mime type will be used. To force jpeg, for example, use `image/jpeg`. See `resizeWidth` for more information.                                                                                                                                                                                                                                                  |
| `resizeQuality`         | `0.8`       | The quality of the resized images. See `resizeWidth`.                                                                                                                                                                                                                                                                                                                                                                                                             |
| `resizeMethod`          | `"contain"` | How the images should be scaled down in case both, `resizeWidth` and `resizeHeight` are provided. Can be either `contain` or `crop`.                                                                                                                                                                                                                                                                                                                              |
| `filesizeBase`          | `1000`      | The base that is used to calculate the \*\*displayed\*\* filesize. You can change this to 1024 if you would rather display kibibytes, mebibytes, etc... 1024 is technically incorrect, because `1024 bytes` are `1 kibibyte` not `1 kilobyte`. You can change this to `1024` if you don't care about validity.                                                                                                                                                    |
| `maxFiles`              | `null`      | If not `null` defines how many files this Dropzone handles. If it exceeds, the event `maxfilesexceeded` will be called. The dropzone element gets the class `dz-max-files-reached` accordingly so you can provide visual feedback.                                                                                                                                                                                                                                |
| `headers`               | `null`      | An optional object to send additional headers to the server. Eg: `{ "My-Awesome-Header": "header value" }`                                                                                                                                                                                                                                                                                                                                                        |
| `clickable`             | `true`      | <p>If <code>true</code>, the dropzone element itself will be clickable, if <code>false</code> nothing will be clickable.<br>You can also pass an HTML element, a CSS selector (for multiple elements) or an array of those. In that case, all of those elements will trigger an upload when clicked.</p>                                                                                                                                                          |
| `ignoreHiddenFiles`     | `true`      | Whether hidden files in directories should be ignored.                                                                                                                                                                                                                                                                                                                                                                                                            |
| `acceptedFiles`         | `null`      | <p>The default implementation of <code>accept</code> checks the file's mime type or extension against this list. This is a comma separated list of mime types or file extensions.<br>Eg.: <code>image/\*,application/pdf,.psd</code><br>If the Dropzone is <code>clickable</code> this option will also be used as [<code>accept</code>](https://developer.mozilla.org/en-US/docs/HTML/Element/input#attr-accept) parameter on the hidden file input as well.</p> |
| `acceptedMimeTypes`     | `null`      | \*\*Deprecated!\*\* Use acceptedFiles instead.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `autoProcessQueue`      | `true`      | <p>If false, files will be added to the queue but the queue will not be processed automatically. This can be useful if you need some additional user input before sending files (or if you want want all files sent at once). If you're ready to send the file simply call <code>myDropzone.processQueue()</code>.<br>See the [enqueuing file uploads](#enqueuing-file-uploads) documentation section for more information.</p>                                   |
| `autoQueue`             | `true`      | If false, files added to the dropzone will not be queued by default. You'll have to call `enqueueFile(file)` manually.                                                                                                                                                                                                                                                                                                                                            |
| `addRemoveLinks`        | `false`     | If `true`, this will add a link to every file preview to remove or cancel (if already uploading) the file. The `dictCancelUpload`, `dictCancelUploadConfirmation` and `dictRemoveFile` options are used for the wording.                                                                                                                                                                                                                                          |
| `previewsContainer`     | `null`      | Defines where to display the file previews – if `null` the Dropzone element itself is used. Can be a plain `HTMLElement` or a CSS selector. The element should have the `dropzone-previews` class so the previews are displayed properly.                                                                                                                                                                                                                         |
| `disablePreviews`       | `false`     | Set this to `true` if you don't want previews to be shown.                                                                                                                                                                                                                                                                                                                                                                                                        |
| `hiddenInputContainer`  | `"body"`    | <p>This is the element the hidden input field (which is used when clicking on the dropzone to trigger file selection) will be appended to. This might be important in case you use frameworks to switch the content of your page.<br>Can be a selector string, or an element directly.</p>                                                                                                                                                                        |
| `capture`               | `null`      | If null, no capture type will be specified If camera, mobile devices will skip the file selection and choose camera If microphone, mobile devices will skip the file selection and choose the microphone If camcorder, mobile devices will skip the file selection and choose the camera in video mode On apple devices multiple must be set to false. AcceptedFiles may need to be set to an appropriate mime type (e.g. "image/\*", "audio/\*", or "video/\*"). |
| `renameFilename`        | `null`      | \*\*Deprecated\*\*. Use `renameFile` instead.                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `renameFile`            | `null`      | A function that is invoked before the file is uploaded to the server and renames the file. This function gets the `File` as argument and can use the `file.name`. The actual name of the file that gets used during the upload can be accessed through `file.upload.filename`.                                                                                                                                                                                    |
| `forceFallback`         | `false`     | If `true` the fallback will be forced. This is very useful to test your server implementations first and make sure that everything works as expected without dropzone if you experience problems, and to test how your fallbacks will look.                                                                                                                                                                                                                       |


# Layout

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

```markup
<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.

To overwrite the default template, use the `previewTemplate` config.

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%` to `100%` 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` config), you can simply insert elements in the template with the `data-dz-remove` attribute. Example:

```markup
<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 if you want your Dropzone to look like the example dropzone.

See the [Theming](/configuration/theming) section, for a more in depth look at how to completely change Dropzone’s UI.

I created an example where I made Dropzone look and feel exactly the way jQuery File Uploader does with a few lines of configuration code. [Check it out!](https://www.dropzonejs.com/bootstrap.html)


# 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:

```javascript
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`.

```javascript
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.
};
```

If you want Dropzone to display an image you have on your server, you can use:

```javascript
// callback and crossOrigin are optional
let mockFile = { name: "Filename", size: 12345 };
myDropzone.displayExistingFile(mockFile, 'https://image-url');
```

See the FAQ on [How to show files stored on server](https://github.com/dropzone/dropzone/discussions/1909).


# Upload Queue

When a file gets added to the dropzone, its `status` gets set to `Dropzone.QUEUED`(after the `accept` function check passes) which means that the file is now in the queue.

If you have the option `autoProcessQueue` set to `true` then the queue is immediately processed, after a file is dropped or an upload finished, by calling`.processQueue()` which checks how many files are currently uploading, and if it’s less than `options.parallelUploads`, `.processFile(file)` is called.

If you set `autoProcessQueue` to `false`, then `.processQueue()` is never called implicitly. This means that you have to call it yourself when you want to upload all files currently queued.


# Events

Dropzone triggers events when processing files, to which you can register easily, by calling `.on(eventName, callbackFunction)` on your Dropzone **instance:**

```javascript
let myDropzone = Dropzone("#my-element", { /* options */ });
myDropzone.on("addedfile", file => {
  console.log("A file has been added");
});
```

If you're configuring your Dropzone declaratively, then you don't have access to the instance to add events. In these case, you can use the `init` config, which is a function that is invoked when the Dropzone is initialized:

```javascript
Dropzone.options.myElement = {
  // Note: using "function()" here to bind `this` to
  // the Dropzone instance.
  init: function() {
    this.on("addedfile", file => {
      console.log("A file has been added");
    });
  }
};
```

{% hint style="warning" %}
**Careful**: when providing the init function, make sure you use the `function()` syntax instead of the arrow syntax, because otherwise the keyword `this` will not reference the Dropzone instance. For more information read up on the [difference between the arrow function expression and the function expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions).
{% endhint %}

Both ways are perfectly fine, but you need to use the `init()` function if you setup your Dropzone declaratively.

{% hint style="success" %}
Dropzone itself relies heavily on events. Everything that’s visual is created by listening to them. They are a fundamental part of making Dropzone look and feel how you want it to.
{% endhint %}

### List of all events

We will be listing all possible events here soon, but until we do that, you can find all of them, well documented in the [source code](https://github.com/dropzone/dropzone/blob/main/src/options.js#L574). These are the implementations for the default event handles so you can see which arguments they receive. You can ignore the content of them if you aren't interested, or override the default behaviour (explained in the next section).

### Overriding default event handlers

{% hint style="danger" %}
In general **you should never have to do this**, and you should be familiar with the code if you decide to do it.
{% endhint %}

You can also override default event handlers. This should be approached with absolute caution since it can break if you upgrade the library and can also remove default functionality that you might not want to  lose:

```javascript
let myDropzone = Dropzone("#my-element", {
  addedfile: file => {
    // ONLY DO THIS IF YOU KNOW WHAT YOU'RE DOING!
  }
});
```

The difference here, is that the default event handler `addedfile` has been changed, instead of adding a new event handler with `myDropzone.on("addedfile", () => {})`

You should only do this when you really know how Dropzone works, and when you want to [completely theme your Dropzone](/configuration/theming).


# Theming

If you want to theme your Dropzone to look fully customized, in most cases you can simply replace the preview HTML template, adapt your CSS, and maybe create a few additional event listeners.

It's covered in the Layout section.

{% content-ref url="/pages/-MOvr6\_0IGbjdEAgDnGV" %}
[Layout](/configuration/basics/layout)
{% endcontent-ref %}

You will go very far with this approach. As an example, I created an example where I made Dropzone look and feel exactly the way jQuery File Uploader does with a few lines of configuration code. [Check it out!](https://www.dropzone.dev/bootstrap.html)

As you can see, the biggest change is the `previewTemplate`. I then added a few additional event listeners to make it look exactly like the reference.

## Completely change the way Dropzone is displayed

Dropzone itself sets up a lot of event listeners when a Dropzone is created, that handle all your UI. They do stuff like: create a new HTML element, add the `<img>`element when provided with image data (with the `thumbnail` event), update the progress bar when the `uploadprogress` event fires, show a checkmark when the `success` event fires, etc…

*Everything* visual is done in those event handlers. If you would overwrite all of them with empty functions, Dropzone would still be fully functional, but wouldn’t display the dropped files anymore.

> If you like the default look of Dropzone, but would just like to add a few bells and whistles here and there, you should just [add additional event listeners](/configuration/events) instead.

Overwriting the default event listeners, and creating your own, custom Dropzone, would look something like this:

```javascript
// This is an example of completely disabling Dropzone's default behavior.
// Do *not* use this unless you really know what you are doing.
Dropzone.myDropzone.options = {
  previewTemplate: document.querySelector('#template-container').innerHTML,
  // Specifing an event as an configuration option overwrites the default
  // `addedfile` event handler.
  addedfile: function(file) {
    file.previewElement = Dropzone.createElement(this.options.previewTemplate);
    // Now attach this new element some where in your page
  },
  thumbnail: function(file, dataUrl) {
    // Display the image in your file.previewElement
  },
  uploadprogress: function(file, progress, bytesSent) {
    // Display the progress
  }
  // etc...
};
```

Obviously this lacks the actual implementation. Look at the source to see how Dropzone does it internally.

You should use this option if you don’t need any of the default Dropzone UI, but are only interested in Dropzone for it’s event handlers, file upload and drag’n’drop functionality.


# Tutorials

In this section you'll learn how to do more complex things with Dropzone.


# Combine form data with files

Create a form with various other input fields that also acts as a Dropzone.

You want to have a normal form, that you can drop files in, and send the whole form, including the files, with the click of a button? Well, you're in luck. It requires a bit of configuration, but it's not difficult to do.

First off, you need to make sure that Dropzone won't auto process your queue and start uploading each file individually. This is done by setting these properties:

* `autoProcessQueue: false` Dropzone should wait for the user to click a button to upload
* `uploadMultiple: true` Dropzone should upload all files at once (including the form data) not all files individually
* `parallelUploads: 100` that means that they shouldn't be split up in chunks as well
* `maxFiles: 100` and this is to make sure that the user doesn't drop more files than allowed in one request.

This is basically everything you need to do. *Dropzone automatically submits all input fields inside a form that behaves as a Dropzone*.

## Show me the code

This is what a very simple HTML looks like:

```markup
<form id="upload-form" class="dropzone">
  <!-- this is were the previews should be shown. -->
  <div class="previews"></div>
  
  <!-- Now setup your input fields -->
  <input type="email" name="username" />
  <input type="password" name="password" />

  <button type="submit">Submit data and files!</button>
</form>
```

And now for the Dropzone configuration:

```javascript
Dropzone.options.uploadForm = { // The camelized version of the ID of the form element

  // The configuration we've talked about above
  autoProcessQueue: false,
  uploadMultiple: true,
  parallelUploads: 100,
  maxFiles: 100,

  // The setting up of the dropzone
  init: function() {
    var myDropzone = this;

    // First change the button to actually tell Dropzone to process the queue.
    this.element.querySelector("button[type=submit]").addEventListener("click", function(e) {
      // Make sure that the form isn't actually being sent.
      e.preventDefault();
      e.stopPropagation();
      myDropzone.processQueue();
    });

    // Listen to the sendingmultiple event. In this case, it's the sendingmultiple event instead
    // of the sending event because uploadMultiple is set to true.
    this.on("sendingmultiple", function() {
      // Gets triggered when the form is actually being sent.
      // Hide the success button or the complete form.
    });
    this.on("successmultiple", function(files, response) {
      // Gets triggered when the files have successfully been sent.
      // Redirect user or notify of success.
    });
    this.on("errormultiple", function(files, response) {
      // Gets triggered when there was an error sending the files.
      // Maybe show form again, and notify user of error
    });
  }
 
}
```

That's it.


# Tips & Tricks

{% hint style="info" %}
Checkout the [Discussions section on Github](https://github.com/dropzone/dropzone/discussions) for more content.
{% endhint %}

If you do not want the default message at all (»Drop files to upload (or click)«), you can put an element inside your dropzone element with the class `dz-message` and dropzone will not create the message for you.

Dropzone will submit any hidden fields you have in your dropzone form. So this is an easy way to submit additional data. You can also use the `params` option.

Dropzone adds data to the `file` object you can use when events fire. You can access `file.width` and `file.height` if it’s an image, as well as `file.upload`which is an object containing: `progress` (0-100), `total` (the total bytes) and `bytesSent`.

If you want to add additional data to the file upload that has to be specific for each file, you can register for the [`sending`](https://www.dropzonejs.com/#event-sending) event:

```javascript
myDropzone.on("sending", function(file, xhr, formData) {
  // Will send the filesize along with the file as POST data.
  formData.append("filesize", file.size);
});
```

To access the preview html of a file, you can access `file.previewElement`. For example:

```javascript
myDropzone.on("addedfile", function(file) {
  file.previewElement.addEventListener("click", function() {
    myDropzone.removeFile(file);
  });
});
```

If you want the whole body to be a Dropzone and display the files somewhere else you can simply instantiate a Dropzone object for the body, and define the[`previewsContainer`](https://www.dropzonejs.com/#config-previewsContainer) option. The `previewsContainer` should have the`dropzone-previews` or `dropzone` class to properly display the file previews.

```javascript
new Dropzone(document.body, {
  previewsContainer: ".dropzone-previews",
  // You probably don't want the whole body
  // to be clickable to select files
  clickable: false
});
```

Look at the [gitlab wiki](https://gitlab.com/meno/dropzone/wikis/home) for more examples.

If you have any problems using Dropzone, please try to find help on [stackoverflow.com](https://stackoverflow.com/questions/tagged/dropzone.js) by using the `dropzone.js` tag. Only create an issue on GitLab when you think you found a bug or want to suggest a new feature.


# FAQ

For all sorts of questions, please use the [Discussions section on GitHub](https://github.com/dropzone/dropzone/discussions/categories/q-a?discussions_q=category%3AQ%26A+is%3Aanswered+label%3AFAQ).


# Donate

Please consider donating if you like this project. I’ve put a lot of my free time into this project and donations help to justify it. Use the [Paypal](https://www.paypal.com/donate?hosted_button_id=JJCGFEMG39FJ4), [tiptheweb](http://tiptheweb.org/) or my [Bitcoin](https://bitcoin.org/) address:`17nRfhRyaKAn93xmB7SQm9sX8fNUtc66YZ`