Dropzone.js: Versatile JavaScript Drag & Drop File Uploader

Authorenyo

Last UpdateSeptember 12, 2026

LicenseMIT

Features

Drag-and-drop and click-to-select file input.
Multiple-file queues with upload progress.
Image thumbnails and browser-side image resizing.
File type, file size, and file-count validation.
Chunked uploads with retry controls.
Manual queue processing and upload cancellation.
Custom preview markup and event-driven UI behavior.
Raw binary request bodies for Amazon S3 multipart upload workflows.

Use Cases

Profile and media forms with image previews before upload.
CMS asset screens with multi-file queues and progress states.
Large-file uploads split across smaller HTTP requests.
Application forms with browser-side file type and size checks.

How To Use Dropzone.js

Install with npm

Install Dropzone from npm.

npm install dropzone

Import the Dropzone export in your JavaScript entry file. Load the package dropzone.css through your CSS pipeline when you want the default Dropzone theme.

import { Dropzone } from "dropzone";
const uploader = new Dropzone("#upload-area", {
  url: "/api/uploads"
});

Create the upload element before this JavaScript runs.

<div id="upload-area"></div>

Use the standalone browser build

Your browser-first projects can load the version 6 standalone files from a CDN.

<link rel="stylesheet" href="https://unpkg.com/dropzone@6/dist/dropzone.css">
<script src="https://unpkg.com/dropzone@6/dist/dropzone-min.js"></script>
<div id="browser-uploader"></div>
<script>
const uploader = new Dropzone("#browser-uploader", {
  url: "/api/uploads"
});
</script>

Configure file type, size, and file count

Set file filters in the Dropzone configuration object. maxFilesize uses MiB, while acceptedFiles accepts MIME types and file extensions.

const uploader = new Dropzone("#document-uploader", {
  url: "/api/documents",
  acceptedFiles: "image/*,application/pdf,.docx",
  maxFilesize: 12,
  maxFiles: 5,
  addRemoveLinks: true
});

Start the upload queue from a button

Set autoProcessQueue to false when files should wait for another form action. Call processQueue() when the upload can start.

<div id="review-uploader"></div>
<button type="button" id="send-files">Upload selected files</button>

const uploader = new Dropzone("#review-uploader", {
  url: "/api/review-files",
  autoProcessQueue: false,
  maxFiles: 4
});
document.querySelector("#send-files").addEventListener("click", function () {
  uploader.processQueue();
});

Upload large files in chunks

Chunking sends one file through multiple requests. Your backend must save the parts and assemble the completed file.

const uploader = new Dropzone("#archive-uploader", {
  url: "/api/archive-parts",
  chunking: true,
  chunkSize: 2 * 1024 * 1024,
  retryChunks: true,
  retryChunksLimit: 3
});

Send extra request data and run custom validation

Use params for extra request fields and accept for custom file checks.

const uploader = new Dropzone("#contract-uploader", {
  url: "/api/contracts",
  params: {
    source: "contract-form"
  },
  accept: function (file, done) {
    if (file.size === 0) {
      done("Empty files are not accepted.");
      return;
    }
    done();
  }
});

Use declarative discovery in Dropzone 6

Dropzone no longer scans .dropzone elements automatically. Configure the form through Dropzone.options, then call Dropzone.discover() after the form exists.

<form action="/api/photos" class="dropzone" id="photo-dropzone"></form>
<script>
Dropzone.options.photoDropzone = {
  acceptedFiles: "image/*",
  maxFilesize: 8
};
Dropzone.discover();
</script>

Dropzone Configuration Options

Request and Upload Options

Option	Description
`url`	Upload URL. Default: `null`. A URL is required when the element is not a form or the form has no `action`.
`method`	HTTP method as a string or function. Default: `post`.
`withCredentials`	Sets `XMLHttpRequest.withCredentials`. Default: `false`.
`timeout`	XHR timeout in milliseconds. Default: `null`. `null` or `0` disables the timeout.
`parallelUploads`	Maximum number of files processed in parallel. Default: `2`.
`uploadMultiple`	Sends multiple files in one request. Default: `false`. It cannot be used with `chunking` or `binaryBody`.
`paramName`	File field name or a function that returns a field name. Default: `file`.
`headers`	Object containing additional request headers. Default: `null`.
`defaultHeaders`	Adds Dropzone’s default `Accept`, `Cache-Control`, and `X-Requested-With` headers. Default: `true`.
`binaryBody`	Sends the file as the raw request body. Default: `false`. It ignores `params` and cannot be used with `uploadMultiple`.

Chunked Upload Options

Option	Description
`chunking`	Splits a file across multiple requests. Default: `false`. It cannot be used with `uploadMultiple`.
`forceChunking`	Uses the chunking workflow for every file when chunking is active. Default: `false`.
`chunkSize`	Chunk size in bytes. Default: `2 * 1024 * 1024`.
`parallelChunkUploads`	Uploads chunks from one file concurrently. Default: `false`.
`retryChunks`	Retries a failed chunk. Default: `false`.
`retryChunksLimit`	Maximum retry count for a failed chunk. Default: `3`.

File Validation and Queue Options

Option	Description
`maxFilesize`	Maximum accepted file size in MiB. Default: `256`.
`maxFiles`	Maximum number of accepted files. Default: `null`.
`acceptedFiles`	Comma-delimited MIME types or file extensions used by the built-in acceptance check. Default: `null`.
`acceptedMimeTypes`	Deprecated alias for `acceptedFiles`. Default: `null`.
`ignoreHiddenFiles`	Ignores hidden files found inside dropped directories. Default: `true`.
`autoProcessQueue`	Starts queue processing automatically after files enter the queue. Default: `true`.
`autoQueue`	Adds accepted files to the queue automatically. Default: `true`.
`clickable`	Enables click-to-select or assigns one or more clickable elements. Default: `true`.
`capture`	Sets the hidden file input’s capture mode, such as `camera`, `microphone`, or `camcorder`. Default: `null`.

Thumbnail and Image Resize Options

Option	Description
`createImageThumbnails`	Generates thumbnails for accepted image files. Default: `true`.
`maxThumbnailFilesize`	Maximum image size in MB for thumbnail generation. Default: `10`.
`thumbnailWidth`	Thumbnail width. Default: `120`.
`thumbnailHeight`	Thumbnail height. Default: `120`.
`thumbnailMethod`	Thumbnail scaling mode. Accepted values: `crop` or `contain`. Default: `crop`.
`resizeWidth`	Width used to resize images before upload. Default: `null`.
`resizeHeight`	Height used to resize images before upload. Default: `null`.
`resizeMimeType`	MIME type for the resized upload image. Default: `null`, which keeps the source type.
`resizeQuality`	Quality passed to canvas image encoding. Default: `0.8`.
`resizeMethod`	Image resize mode. Accepted values: `contain` or `crop`. Default: `contain`.

Preview and Input Options

Option	Description
`filesizeBase`	Base used to format displayed file sizes. Default: `1000`.
`addRemoveLinks`	Adds remove or cancel links to file previews. Default: `false`.
`previewsContainer`	Element or selector used to contain previews. Default: `null`, which uses the Dropzone element.
`disablePreviews`	Disables preview rendering. Default: `false`.
`hiddenInputContainer`	Container for the hidden file input. Accepts a selector or element. Default: `body`.
`previewTemplate`	HTML string used to create each file preview. Default: Dropzone’s built-in preview template.
`forceFallback`	Forces the fallback file input workflow. Default: `false`.

File Naming Options

Option	Description
`renameFile`	Function that returns the upload filename for a file. Default: `null`.
`renameFilename`	Deprecated filename callback retained for backwards compatibility. Default: `null`. Use `renameFile`.

Message and Localization Options

Option	Description
`dictDefaultMessage`	Initial drop-area message. Default: `Drop files here to upload`.
`dictFallbackMessage`	Message shown when the browser cannot use the Dropzone workflow.
`dictFallbackText`	Text inserted before the fallback form.
`dictFileTooBig`	Message for a file above `maxFilesize`. Supports `{{filesize}}` and `{{maxFilesize}}`.
`dictInvalidFileType`	Message for a file rejected by the built-in file type check.
`dictThumbnailError`	Message for an image that cannot be decoded for thumbnail generation.
`dictResponseError`	Message for an invalid server response. Supports `{{statusCode}}`.
`dictCancelUpload`	Text for the cancel-upload link.
`dictUploadCanceled`	Message emitted after a manual upload cancellation.
`dictCancelUploadConfirmation`	Confirmation text shown before canceling an upload.
`dictRemoveFile`	Text for the remove-file link.
`dictRemoveFileConfirmation`	Optional confirmation text shown before removing a file. Default: `null`.
`dictMaxFilesExceeded`	Message used after the maximum file count is exceeded. Supports `{{maxFiles}}`.
`dictFileSizeUnits`	Labels used by `filesize()` for TB, GB, MB, KB, and bytes.

Configuration Callbacks

Option	Description
`init`	Runs after the Dropzone instance initializes. Default: empty function.
`params`	Object or function for extra request parameters. The default function returns Dropzone chunk metadata for chunked uploads.
`accept`	Custom acceptance callback. Receives `file` and `done`. The default calls `done()`.
`chunksUploaded`	Runs after every chunk for one file has uploaded. Receives `file` and `done`.
`fallback`	Runs when fallback mode is required. The default renders Dropzone’s fallback form.
`resize`	Calculates source and destination dimensions for thumbnail rendering.
`transformFile`	Transforms a file before upload. The default uses the image resize settings when applicable.

Event Handler Options

Every event listed in the Dropzone Events section can also be assigned as a configuration option. Assigning an event handler in the configuration object replaces Dropzone’s default handler for that event. Use .on() when you only need an additional listener.

Option	Description
`drop`	Default UI handler for a file drop.
`dragstart`	Default handler for drag start.
`dragend`	Default UI handler for drag end.
`dragenter`	Default UI handler for drag entry.
`dragover`	Default UI handler while files remain over the Dropzone.
`dragleave`	Default UI handler when dragged files leave the Dropzone.
`reset`	Restores the Dropzone element to its initial state.
`addedfile`	Creates the default preview UI for one file.
`addedfiles`	Default handler for a batch of newly added files.
`removedfile`	Removes the file preview from the DOM.
`thumbnail`	Updates preview thumbnail markup after thumbnail generation.
`error`	Applies the default error state and error message.
`errormultiple`	Default handler for a multiple-file request error.
`processing`	Applies the default processing state to one file.
`processingmultiple`	Default handler when a multiple-file request starts processing.
`uploadprogress`	Updates the default per-file progress UI.
`totaluploadprogress`	Default handler for aggregate upload progress.
`sending`	Default handler just before one file request is sent.
`sendingmultiple`	Default handler just before a multiple-file request is sent.
`success`	Applies the default success state.
`successmultiple`	Default handler for a successful multiple-file request.
`canceled`	Converts a canceled upload into Dropzone’s default error state.
`canceledmultiple`	Default handler for cancellation of a multiple-file request.
`complete`	Applies the default completed state.
`completemultiple`	Default handler after a multiple-file request completes.
`maxfilesexceeded`	Default handler when another file exceeds `maxFiles`.
`maxfilesreached`	Default handler when the accepted file count reaches `maxFiles`.
`queuecomplete`	Default handler after the upload queue has finished.
`paste`	Handler option present in `defaultOptions`. The built-in paste DOM listener is disabled in the v6.1.0 source.

Dropzone Methods

Event Emitter Methods

Method	Description
`on(event, fn)`	Registers a listener for a Dropzone event and returns the instance.
`off(event, fn)`	Removes one listener, all listeners for an event, or every listener when called with no arguments.
`emit(event, ...args)`	Emits a Dropzone event and dispatches the corresponding `dropzone:event` DOM CustomEvent.
`makeEvent(eventName, detail)`	Creates the DOM CustomEvent used by `emit()`.

File State and Queue Methods

Method	Description
`getAcceptedFiles()`	Returns all accepted files.
`getRejectedFiles()`	Returns all rejected files.
`getFilesWithStatus(status)`	Returns files that match one Dropzone status value.
`getQueuedFiles()`	Returns files with `Dropzone.QUEUED` status.
`getUploadingFiles()`	Returns files with `Dropzone.UPLOADING` status.
`getAddedFiles()`	Returns files with `Dropzone.ADDED` status.
`getActiveFiles()`	Returns queued and uploading files.
`addFile(file)`	Adds one file, runs acceptance checks, generates a thumbnail when applicable, and queues it according to the current options.
`enqueueFile(file)`	Moves an accepted added file into the queue.
`enqueueFiles(files)`	Queues multiple files.
`processQueue()`	Processes queued files while respecting `parallelUploads`.
`processFile(file)`	Processes one file.
`processFiles(files)`	Processes a group of files and begins the upload workflow.
`cancelUpload(file)`	Cancels an active or queued upload and updates its status.
`removeFile(file)`	Removes one file and emits `removedfile`.
`removeAllFiles(cancelIfNecessary)`	Removes all non-uploading files. Pass `true` to cancel active uploads too.
`uploadFile(file)`	Passes one file directly to `uploadFiles()`.
`uploadFiles(files)`	Runs file transformation and upload request logic for one or more files.

Preview and Image Methods

Method	Description
`filesize(size)`	Formats a byte count using `filesizeBase` and `dictFileSizeUnits`.
`resizeImage(file, width, height, resizeMethod, callback)`	Resizes an image before upload and passes the resized Blob to the callback.
`createThumbnail(file, width, height, resizeMethod, fixOrientation, callback)`	Reads a File and generates thumbnail data.
`createThumbnailFromUrl(file, width, height, resizeMethod, fixOrientation, callback, crossOrigin)`	Generates a thumbnail from an image URL.
`displayExistingFile(mockFile, imageUrl, callback, crossOrigin, resizeThumbnail)`	Adds an existing server file to the Dropzone preview UI.

Lifecycle and Low-level Instance Methods

These methods are exposed on the v6.1.0 class. Several are used by Dropzone’s own workflow and are less stable integration points than the queue, file, and event methods above.

Method	Description
`init()`	Builds the hidden input, default message, listeners, and initial instance state.
`destroy()`	Disables the instance, removes files and its hidden input, and detaches the instance from the element.
`updateTotalUploadProgress()`	Recalculates aggregate progress and emits `totaluploadprogress`.
`getFallbackForm()`	Returns the fallback upload fields or form.
`getExistingFallback()`	Finds an existing fallback element inside the Dropzone.
`setupEventListeners()`	Attaches the stored DOM event listeners.
`removeEventListeners()`	Detaches the stored DOM event listeners.
`disable()`	Disables interaction, removes DOM listeners, and cancels files.
`enable()`	Re-enables interaction and DOM listeners.
`drop(event)`	Handles a file drop and passes dropped files into Dropzone.
`paste(event)`	Processes clipboard file items when invoked. The built-in paste DOM listener is disabled in v6.1.0.
`handleFiles(files)`	Passes a list of files to `addFile()`.
`accept(file, done)`	Runs built-in size, type, and file-count checks before calling the configured `accept` callback.
`resolveOption(option, ...args)`	Returns a plain option value or calls a function-valued option with the supplied arguments.
`submitRequest(xhr, formData, files)`	Sends the prepared XHR with either FormData or a raw binary body.

Static Methods and Helpers

Method	Description
`Dropzone.optionsForElement(element)`	Returns the declarative configuration stored for an element ID.
`Dropzone.forElement(element)`	Returns the Dropzone instance attached to an element or selector.
`Dropzone.discover()`	Finds `.dropzone` elements and instantiates those not disabled through `Dropzone.options`.
`Dropzone.isBrowserSupported()`	Checks the browser APIs and Dropzone’s blocked-browser rules.
`Dropzone.dataURItoBlob(dataURI)`	Converts a base64 data URI to a Blob.
`Dropzone.createElement(string)`	Creates one DOM node from an HTML string.
`Dropzone.elementInside(element, container)`	Checks whether an element is the container or one of its descendants.
`Dropzone.getElement(el, name)`	Resolves a selector or DOM element and throws for an invalid value.
`Dropzone.getElements(els, name)`	Resolves selectors, DOM elements, or element arrays into an element list.
`Dropzone.confirm(question, accepted, rejected)`	Runs the confirmation callback flow. The default implementation uses `window.confirm()`.
`Dropzone.isValidFile(file, acceptedFiles)`	Checks a file against the `acceptedFiles` MIME type and extension syntax.
`Dropzone.uuidv4()`	Generates the UUID used for upload metadata.

Static Properties and File Status Constants

Property	Description
`Dropzone.options`	Object used for per-element declarative configurations.
`Dropzone.instances`	Array containing active Dropzone instances.
`Dropzone.blockedBrowsers`	Regular expressions for browsers that expose required APIs but have known incompatible behavior.
`Dropzone.ADDED`	Status string `added`.
`Dropzone.QUEUED`	Status string `queued`.
`Dropzone.ACCEPTED`	Backwards-compatible alias of `Dropzone.QUEUED`.
`Dropzone.UPLOADING`	Status string `uploading`.
`Dropzone.PROCESSING`	Alias of `Dropzone.UPLOADING`.
`Dropzone.CANCELED`	Status string `canceled`.
`Dropzone.ERROR`	Status string `error`.
`Dropzone.SUCCESS`	Status string `success`.

Dropzone Events

Register event listeners with uploader.on(eventName, callback). Dropzone v6.1.0 exposes the following events in its instance event list.

Event	Fires When
`drop`	Files are dropped onto the Dropzone element.
`dragstart`	A drag operation starts over the Dropzone.
`dragend`	A drag operation ends.
`dragenter`	Dragged files enter the Dropzone.
`dragover`	Dragged files move over the Dropzone.
`dragleave`	Dragged files leave the Dropzone.
`addedfile`	One file is added.
`addedfiles`	A group of files is added through a file selection or drop.
`removedfile`	A file is removed.
`thumbnail`	A thumbnail is ready for an image file.
`error`	One file encounters validation or upload failure.
`errormultiple`	A request containing multiple files fails.
`processing`	One file enters the upload-processing state.
`processingmultiple`	A multiple-file request enters the processing state.
`uploadprogress`	Progress changes for one file. The callback receives the file, percentage, and bytes sent.
`totaluploadprogress`	Aggregate upload progress changes. The callback receives percentage, total bytes, and total bytes sent.
`sending`	One file request is about to be sent.
`sendingmultiple`	A multiple-file request is about to be sent.
`success`	One file finishes successfully.
`successmultiple`	A multiple-file request finishes successfully.
`canceled`	One upload is canceled.
`canceledmultiple`	A multiple-file request is canceled.
`complete`	One file finishes with either success or error.
`completemultiple`	A multiple-file request finishes.
`reset`	The file list becomes empty and the Dropzone returns to its initial state.
`maxfilesexceeded`	A newly added file exceeds `maxFiles`.
`maxfilesreached`	The accepted file count reaches `maxFiles`.
`queuecomplete`	No added, queued, or uploading files remain after completion.

uploader.on("sending", function (file, xhr, formData) {
  formData.append("documentId", "invoice-482");
});
uploader.on("uploadprogress", function (file, progress, bytesSent) {
  console.log(file.name, progress, bytesSent);
});
uploader.on("success", function (file, response) {
  console.log("Uploaded:", file.name, response);
});
uploader.on("error", function (file, message) {
  console.error("Upload failed:", file.name, message);
});
uploader.on("queuecomplete", function () {
  console.log("All queued uploads finished");
});

Server-side Upload Requirements

Dropzone handles the browser side of the upload. Your server endpoint receives and stores the files. Normal uploads use multipart form data and the default field name is file.

Client-side limits such as acceptedFiles and maxFilesize improve form feedback. The server must validate file type, size, permissions, and storage rules before accepting uploaded data.

Chunked uploads send chunk metadata through params. The backend must save and assemble the parts. The chunksUploaded callback can run finalization logic after every chunk for a file has finished.

Alternatives and Related Resources

FAQs

Q: Does Dropzone.js upload and store files on the server?
A: Dropzone sends files from the browser to the configured URL. Your backend must receive, validate, and store each upload.

Q: Why does a class="dropzone" form not initialize automatically in Dropzone 6?
A: Dropzone 6 removed automatic discovery. Call Dropzone.discover() after the form exists, or create the Dropzone instance directly with new Dropzone(...).

Q: How do I restrict file types and file sizes?
A: Set acceptedFiles, maxFilesize, and maxFiles in the configuration object. Apply equivalent validation on the server.

Q: How do I wait for a button click before uploading?
A: Set autoProcessQueue to false. Call processQueue() from the button handler when the files are ready for transfer.

Changelog

v6.2.1 (09/12/2026)

Update

v6.2.0 (09/07/2026)

addedfiles now reports the files found inside a dropped folder.
parallelChunkUploads: true now starts at most parallelUploads chunks at a time rather than every chunk of the file at once.
Add resizeTransparencyFill, the color shown through transparent parts of a resized image.

v6.1.0 (09/05/2026)

Introduced dictThumbnailError for image files that cannot be decoded.
Corrected chunk offsets when chunkSize arrives as a string.
Prevented preview thumbnails from being dragged back into the upload area as duplicate files.
Corrected zero-byte uploads when forced chunking is active.

v6.0.0 (09/05/2026)

Promoted the 6.0 line to stable.
Removed Internet Explorer compatibility and several legacy APIs and distribution files.
Reduced bundle size for the current browser baseline.
Kept the API unchanged from 6.0.0-beta.2.