\n ![]()
\n
\n \n \n
\n
✔
\n ✘
\n \n![\"Dropzone.js\"](\"http://www.dropzonejs.com/images/new-logo.svg\"){kind=logo}
\n\nDropzone.js is a light weight JavaScript library that turns an HTML element into a dropzone.\nThis means that a user can drag and drop a file onto it, and the file gets uploaded to the server via AJAX.\n\n* * *\n\n_If you want support, please use [stackoverflow](http://stackoverflow.com/) with the `dropzone.js` tag and not the\nGitLab issues tracker. Only post an issue here if you think you discovered a bug or have a feature request._\n\n* * *\n\n**Please read the [contributing guidelines](CONTRIBUTING.md) before you start working on Dropzone!**\n\n![\"Dropzone](\"http://i.imgur.com/Xf7QvVG.png\")
\n\n## Main features\n\n- Image thumbnail previews. Simply register the callback `thumbnail(file, data)` and display the image wherever you like\n- Retina enabled\n- Multiple files and synchronous uploads\n- Progress updates\n- Support for large files\n- Complete theming. The look and feel of Dropzone is just the default theme. You\n can define everything yourself by overwriting the default event listeners.\n- Browser image resizing (resize the images before you upload them to your server)\n- Well tested\n\n## Documentation\n\nFor the full documentation and installation please visit [www.dropzonejs.com](http://www.dropzonejs.com)\n\nPlease also refer to the [FAQ](https://github.com/enyo/dropzone/wiki/FAQ).\n\n## Examples\n\nFor examples, please see the [GitLab wiki](https://gitlab.com/meno/dropzone/wikis/home).\n\n\n# Installation\n\nYou probably only need to look at the [simple example](http://www.dropzonejs.com/examples/simple.html) ([source](https://gitlab.com/meno/dropzone/raw/master/website/examples/simple.html))\nto get started. Continue reading for step by step instructions and different\ninstallation approaches.\n\n* * *\n\nDownload the standalone [dropzone.js](https://gitlab.com/meno/dropzone/builds/artifacts/master/file/dist/dropzone.js?job=release)\nand include it like this:\n\n```html\n\n```\n\nDropzone is now activated and available as `window.Dropzone`.\n\n> Dropzone does *not* handle your file uploads on the server. You have to implement\n> the code to receive and store the file yourself. See the section\n> [Server side implementation](#server-side-implementation) for more information.\n\nThis is all you need to get dropzone up and running, but if you want it to look\nlike the dropzone on this page, you’ll need to use the **dropzone.css**\nin the [dist folder](https://gitlab.com/meno/dropzone/builds/artifacts/master/download?job=release).\n\n\nWith RequireJS\n--------------\n\nDropzone is also available as an [AMD module](https://github.com/amdjs/amdjs-api/wiki/AMD)\nfor [RequireJS](http://requirejs.org).\n\nYou can find the [dropzone-amd-module](https://gitlab.com/meno/dropzone/builds/artifacts/master/file/dist/dropzone-amd-module.js?job=release)\nin the dist folder.\n\n\n\n# Usage\n\nThe typical way of using dropzone is by creating a form element with the class `dropzone`:\n\n```html\n\n```\n\nThat’s it. Dropzone will find all form elements with the class dropzone,\nautomatically attach itself to it, and upload files dropped into it to the\nspecified `action` attribute. The uploaded files can be handled just as if\nthere would have been a html input like this:\n\n```html\n\n```\n\nIf you want another name than `file` you can [configure dropzone](#configuration)\nwith the option `paramName`.\n\n\nIf you want your file uploads to work even without JavaScript, you can include\nan element with the class `fallback` that dropzone will remove if the browser\nis supported. If the browser isn’t supported, Dropzone will not create fallback\nelements if there is a fallback element already provided. (Obviously, if the\nbrowser doesn’t support JavaScript, the form will stay as is)\n\nTypically this will look like this:\n\n```html\n\n```\n\n\n\nCreate dropzones programmatically\n---------------------------------\n\nAlternatively you can create dropzones programmaticaly (even on non `form`\nelements) by instantiating the `Dropzone` class\n\n```js\n// Dropzone class:\nvar myDropzone = new Dropzone(\"div#myId\", { url: \"/file/post\"});\n```\n\nor if you use jQuery, you can use the jQuery plugin Dropzone ships with:\n\n```js\n// jQuery\n$(\"div#myId\").dropzone({ url: \"/file/post\" });\n```\n\n> Don’t forget to specify an `url` option if you’re not using a form element,\n> since Dropzone doesn’t know where to post to without an `action` attribute.\n\n\n\nServer side implementation\n--------------------------\n\nDropzone does *not* provide the server side implementation of handling the files,\nbut the way files are uploaded is identical to simple file upload forms like this:\n\n```html\n\n```\n\nTo handle basic file uploads on the server, please look at the corresponding\ndocumentation. Here are a few documentations, if you think I should add some,\nplease contact me.\n\n- [AngularJS and Spring](http://www.cantangosolutions.com/blog/Easy-File-Upload-Using-DropzoneJS-AngularJs-And-Spring)\n- [NodeJS with express](http://howtonode.org/really-simple-file-uploads)\n- [Ruby on rails](http://guides.rubyonrails.org/form_helpers.html#uploading-files)\n- [Complete PHP tutorial](http://www.startutorial.com/articles/view/how-to-build-a-file-upload-form-using-dropzonejs-and-php) by startutorial.com\n- [Basic PHP file upload](http://www.php.net/manual/en/features.file-upload.post-method.php#example-354)\n- [Tutorial for Dropzone and Lavarel (PHP)](http://maxoffsky.com/code-blog/howto-ajax-multiple-file-upload-in-laravel/) written by Maksim Surguy\n- [Symfony2 and Amazon S3](http://www.jesuisundev.fr/upload-drag-drop-via-dropzonejs-symfony2-on-cloud-amazon-s3/)\n- [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/)\n- [Servicestack and Dropzone](http://www.buildclassifieds.com/2016/01/08/uploading-images-servicestack-and-dropzone/)\n- [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)\n- [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)\n\nPaid documentations:\n\n- [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.\n\n\nPlease look at the [Dropzone FAQ](https://github.com/enyo/dropzone/wiki/FAQ) if\nyou need more information.\n\n\n\n\n# Configuration\n\nThere are two ways to configure dropzones.\n\nThe obvious way is to pass an options object when instantiating a dropzone\nprogrammatically like in the previous [create dropzones programmatically](#create-dropzones-programmatically)\nsection.\n\nBut if you just have HTML elements with the `dropzone` class, then you don’t\nprogrammatically instantiate the objects, so you have to store the configuration\nsomewhere so Dropzone knows how to configure the dropzones when instantiating\nthem.\n\nThis is done with the `Dropzone.options` object.\n\n```js\n// \"myAwesomeDropzone\" is the camelized version of the HTML element's ID\nDropzone.options.myAwesomeDropzone = {\n paramName: \"file\", // The name that will be used to transfer the file\n maxFilesize: 2, // MB\n accept: function(file, done) {\n if (file.name == \"justinbieber.jpg\") {\n done(\"Naha, you don't.\");\n }\n else { done(); }\n }\n};\n```\n\n\nIf you want to disable the auto discover behaviour of Dropzone, you can either disable\nit on a per element basis, or in general:\n\n```js\n// Prevent Dropzone from auto discovering this element:\nDropzone.options.myAwesomeDropzone = false;\n// This is useful when you want to create the\n// Dropzone programmatically later\n\n// Disable auto discover for all elements:\nDropzone.autoDiscover = false;\n```\n\n\n[List of configuration options](http://www.dropzonejs.com/#configuration-options)\n\n\n> You can also overwrite all default event actions in the options. So if you provide the option `drop` you can overwrite the default `drop` event handler.\n> *You should be familiar with the code if you do that because you can easily break the upload like this.*\n> If you just want to do additional stuff, like adding a few classes here and there, **[listen to the events](#events) instead**!\n\n\n## Enqueuing file uploads\n\nWhen a file gets added to the dropzone, its `status` gets set to `Dropzone.QUEUED`\n(after the `accept` function check passes) which means that the file is now\nin the queue.\n\nIf you have the option `autoProcessQueue` set to `true` then the queue is immediately\nprocessed, after a file is dropped or an upload finished, by calling\n`.processQueue()` which checks how many files are currently uploading,\nand if it’s less than `options.parallelUploads`, `.processFile(file)` is called.\n\nIf you set `autoProcessQueue` to `false`, then `.processQueue()` is never called\nimplicitly. This means that you have to call it yourself when you want to\nupload all files currently queued.\n\n\n\n## Layout\n\nThe HTML that is generated for each file by dropzone is defined with the option `previewTemplate` which defaults to this:\n\n```html\n![\"Click](\"removebutton.png\")
\n```\n\nYou are not forced to use those conventions though. If you override all the default event listeners\nyou can completely rebuild your layout from scratch.\n\nSee the installation section on how to add the stylesheet and spritemaps if you want your dropzone to look like the one on this page.\n\nSee the [Theming](#theming) section, for a more in depth look at how to change Dropzone’s UI.\n\nI created an example where I made Dropzone look and feel exactly the way jQuery\nFile Uploader does with a few lines of configuration code. [Check it out!](/bootstrap.html)\n\n> Again, please look at the [Dropzone FAQ](https://github.com/enyo/dropzone/wiki/FAQ) if\n> you’re still unclear about some features.\n\n\n\n## Dropzone methods\n\nIf you want to remove an added file from the dropzone, you can call `.removeFile(file)`.\nThis method also triggers the `removedfile` event.\n\nHere’s an example that would automatically remove a file when it’s finished uploading:\n\n```js\nmyDropzone.on(\"complete\", function(file) {\n myDropzone.removeFile(file);\n});\n```\n\nIf you want to remove all files, simply use `.removeAllFiles()`. Files that are\nin the process of being uploaded won’t be removed. If you want files that are\ncurrently uploading to be canceled, call `.removeAllFiles(true)` which will\ncancel the uploads.\n\n* * *\n\nIf you have `autoProcessQueue` disabled, you’ll need to call `.processQueue()`\nyourself.\n\nThis can be useful if you want to display the files and let the user click an\naccept button to actually upload the file(s).\n\n* * *\n\nTo access all files in the dropzone, use `myDropzone.files`.\n\nTo get\n\n- all accepted files: `.getAcceptedFiles()`\n- all rejected files: `.getRejectedFiles()`\n- all queued files: `.getQueuedFiles()`\n- all uploading files: `.getUploadingFiles()`\n\n* * *\n\nIf you do not need a dropzone anymore, just call `.disable()` on the object. This\nwill remove all event listeners on the element, and clear all file arrays. To\nreenable a Dropzone use `.enable()`.\n\n* * *\n\nIf you don’t like the default browser modals for `confirm` calls,\nyou can handle them yourself by overwriting `Dropzone.confirm`.\n\n```js\nDropzone.confirm = function(question, accepted, rejected) {\n // Ask the question, and call accepted() or rejected() accordingly.\n // CAREFUL: rejected might not be defined. Do nothing in that case.\n};\n```\n\n* * *\n\nIf you want Dropzone to download a file from your server and display it,\nyou can use\n\n```js\n// callback and crossOrigin are optional\nmyDropzone.createThumbnailFromUrl(file, imageUrl, callback, crossOrigin);\n```\n\nSee the FAQ on [How to show files stored on server](https://github.com/enyo/dropzone/wiki/FAQ#how-to-show-files-already-stored-on-server)\n for more information.\n\n\n\n# Events\n\nDropzone triggers events when processing files, to which you can register easily,\nby calling `.on(eventName, callbackFunction)` on your _instance_.\n\nSince listening to events can only be done on _instances_ of Dropzone, the best\nplace to setup your event listeners, is in the `init` function:\n\n```js\n// The recommended way from within the init configuration:\nDropzone.options.myAwesomeDropzone = {\n init: function() {\n this.on(\"addedfile\", function(file) { alert(\"Added file.\"); });\n }\n};\n```\n\nIf you [create your Dropzones programmatically](#create-dropzones-programmatically),\nyou can setup your event listeners on your instances, like this:\n\n```js\n// This example uses jQuery so it creates the Dropzone, only when the DOM has\n// loaded.\n\n// Disabling autoDiscover, otherwise Dropzone will try to attach twice.\nDropzone.autoDiscover = false;\n// or disable for specific dropzone:\n// Dropzone.options.myDropzone = false;\n\n$(function() {\n // Now that the DOM is fully loaded, create the dropzone, and setup the\n // event listeners\n var myDropzone = new Dropzone(\"#my-dropzone\");\n myDropzone.on(\"addedfile\", function(file) {\n /* Maybe display some more file information on your page */\n });\n})\n```\n\nThis is a bit more complex, and not necessary unless you have a good reason\nto instantiate Dropzones programmatically.\n\n> Dropzone itself relies heavily on events. Everything that’s visual is created\nby listening to them. Those event listeners are setup in the default configuration\nof every Dropzone and can be overwritten, thus replacing the default behavior\nwith your own event callback.\n\nYou should only do this when you really know how Dropzone works, and when you\nwant to [completely theme your Dropzone](#theming)\n\n\n[List of events](http://www.dropzonejs.com/#event-list)\n\n\n## Theming\n\nIf you want to theme your Dropzone to look fully customized, in most cases you\ncan simply [replace the preview HTML template](#layout), adapt your CSS, and maybe create\na few additional event listeners.\n\nYou will go very far with this approach. As an example, I created an example\nwhere I made Dropzone look and feel exactly the way jQuery File Uploader does\nwith a few lines of configuration code. [Check it out!](/bootstrap.html)\n\nAs you can see, the biggest change is the `previewTemplate`. I then added a few\nadditional event listeners to make it look exactly like the reference.\n\n*You can however, implement your UI completely from scratch.*\n\nDropzone itself sets up a lot of event listeners when a Dropzone is created,\nthat handle all your UI. They do stuff like: create a new HTML element,\nadd the `