dropzone upload only one file

dropzone upload only one file

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Enforcing Single-File State in Dropzone.js

Setting maxFiles: 1 in your Dropzone configuration is the correct starting point, but it only prevents a user from adding a second file to the queue; it does not automatically invalidate an existing upload. When you drop a new file while one is already present in the accepted state, Dropzone treats them as separate entities unless you explicitly remove the previous one. To achieve the "replace" behavior where the first file is discarded before the second one uploads, you need to intercept the addedfile event and clear the instance's internal state manually.

Here is how to implement this logic:

$(document).ready(function() {
    var myDropzone = new Dropzone("#my-dropzone", {
        url: "upload.php",
        maxFiles: 1,
        addAfterUpload: false, // Optional: prevents re-rendering if needed
        init: function() {
            this.on("addedfile", function(file) {
                // Check if there is already a file accepted or queued
                if (this.files.length > 0) {
                    // Remove the first (and currently only valid) file
                    var currentFile = this.files[0];
                    
                    // Trigger removal of the previous file
                    this.removeFile(currentFile);
                    
                    // Optional: Visual feedback to the user
                    console.log("Previous file removed. New file is now queued.");
                }
                
                // Remove the newly added file from the accepted list immediately
                // so it doesn't sit there while waiting for the previous slot to clear.
                this.removeFile(file);
            });
        }
    });
});

The core mechanism here relies on the removeFile method provided by Dropzone's API. When a user drops a new image, the addedfile event fires immediately. At that exact moment, your instance already holds a reference to the previously accepted file in the this.files array. By calling this.removeFile(file) inside the event handler, you effectively tell the library, "Forget this new file for now."

However, there is a critical timing nuance you must respect. The previous logic above removes the new file immediately upon addition. A slightly more robust pattern often involves checking if the queue is non-empty and removing the old one first, then allowing the new one to enter the accepted state naturally, or removing it immediately after adding to ensure maxFiles: 1 remains strictly enforced without visual clutter.

If you remove the file immediately inside addedfile, Dropzone's internal logic ensures that the upload process for the previous file (if it hasn't finished) is halted and cleaned up. This prevents duplicate uploads where one file finishes processing while another has already replaced it in the queue.

It is also important to consider the server-side interaction. Your PHP endpoint (upload.php) must handle the scenario where a POST request comes in but the client might not have sent a specific parameter indicating replacement, or conversely, ensure that if multiple multipart/form-data fields are sent (which can happen depending on browser behavior during rapid clicks), your backend processes only the intended file.

In many modern Laravel projects, handling this single-file constraint is often done via middleware or queue listeners to ensure data integrity, but at the client level, managing the Dropzone instance directly is the most responsive approach. If you are building a complex SaaS platform where this specific upload behavior is critical, resources like those found at https://laravelcompany.com can provide deeper insights into backend validation patterns that complement frontend dropzone configurations.

One common pitfall to avoid is relying solely on maxFiles: 1. Without the event listener logic described above, users can still see two files in the UI for a brief moment before one disappears, or worse, they might trigger an upload failure if the server rejects multiple file submissions. Explicitly managing the lifecycle of the file objects within the addedfile event guarantees a seamless user experience where the interface always reflects exactly one pending operation.

Our network