StackPractices
intermediate Por Mathias Paulenko

Subida de Archivos Drag and Drop en JavaScript con HTML5

Implementa subida de archivos drag and drop nativa con HTML5 en JavaScript: zona de arrastre, validación, barra de progreso y vistas previas.

Visión General

Meter archivos en una app web suele significar abrir un diálogo de selección de archivos. La HTML5 Drag and Drop API es la forma nativa del navegador de arrastrar archivos y datos sobre elementos de la página — el camino más cómodo: los usuarios arrastran los archivos directamente sobre tu página, sin librerías de terceros. Esta recipe construye una zona de arrastre (drop zone) paso a paso: valida archivos por tipo y tamaño, los sube con FormData mientras sigue el progreso, y da respuesta visual mientras el usuario arrastra.

Cuándo Usar

  • Necesitas un área de subida donde los usuarios puedan soltar archivos en vez de hacer click en un botón
  • Quieres rechazar archivos inválidos del lado del cliente antes de que lleguen al servidor
  • Necesitas mostrar el progreso de subida en archivos grandes
  • Estás construyendo un componente de subida para una galería de imágenes o una interfaz de gestión de documentos
  • Evítalo si tu audiencia es mayoritariamente móvil — el drag and drop apenas funciona en pantallas táctiles, así que un <input type="file"> simple es mejor opción ahí

Solución

Markup de la drop zone

Los snippets de abajo asumen que existe este markup mínimo en la página — una drop zone alcanzable también por teclado, un contenedor de errores anunciado a lectores de pantalla, y placeholders para las barras de progreso y las vistas previas:

<div id="drop-zone" role="button" tabindex="0"
     aria-label="Suelta archivos aquí o pulsa Enter para explorar">
    Suelta archivos aquí o pulsa Enter para explorar
</div>
<div id="upload-errors" aria-live="polite"></div>
<div id="upload-list"></div>
<div id="preview-grid"></div>
#drop-zone {
    border: 2px dashed #94a3b8;
    border-radius: 8px;
    padding: 2rem;
    text-align: center;
    cursor: pointer;
}

#drop-zone.drag-over {
    border-color: #2563eb;
    background: #eff6ff;
}

.upload-item { margin: 0.5rem 0; }

.progress-bar {
    height: 8px;
    background: #e5e7eb;
    border-radius: 4px;
}

.progress-fill {
    width: 0;
    height: 100%;
    background: #2563eb;
    border-radius: 4px;
    transition: width 0.2s;
}

El par role="button" + tabindex="0" hace que la zona sea enfocable por teclado, y aria-live="polite" en el contenedor de errores anuncia los rechazos sin robar el foco.

Drop zone básica

const dropZone = document.getElementById("drop-zone");

dropZone.addEventListener("dragover", (e) => {
    e.preventDefault();
    dropZone.classList.add("drag-over");
});

dropZone.addEventListener("dragleave", () => {
    dropZone.classList.remove("drag-over");
});

dropZone.addEventListener("drop", (e) => {
    e.preventDefault();
    dropZone.classList.remove("drag-over");

    const files = Array.from(e.dataTransfer.files);
    console.log(`Se soltaron ${files.length} archivos`);

    files.forEach(file => {
        console.log(`${file.name} — ${file.size} bytes — ${file.type}`);
    });
});

Drop zone con validación de archivos

Las validaciones del cliente son un filtro de UX, no seguridad — combínalas con validación de subida de archivos del lado del servidor o un .exe renombrado pasará por image/png.

const MAX_SIZE = 5 * 1024 * 1024; // 5 MB
const ALLOWED_TYPES = ["image/jpeg", "image/png", "image/webp", "application/pdf"];

function setupDropZone(elementId) {
    const dropZone = document.getElementById(elementId);

    dropZone.addEventListener("dragover", (e) => {
        e.preventDefault();
        dropZone.classList.add("drag-over");
    });

    dropZone.addEventListener("dragleave", (e) => {
        if (e.target === dropZone) {
            dropZone.classList.remove("drag-over");
        }
    });

    dropZone.addEventListener("drop", (e) => {
        e.preventDefault();
        dropZone.classList.remove("drag-over");

        const files = Array.from(e.dataTransfer.files);
        const valid = [];
        const errors = [];

        for (const file of files) {
            if (!ALLOWED_TYPES.includes(file.type)) {
                errors.push(`${file.name}: tipo inválido (${file.type})`);
                continue;
            }

            if (file.size > MAX_SIZE) {
                errors.push(`${file.name}: demasiado grande (${formatSize(file.size)})`);
                continue;
            }

            valid.push(file);
        }

        errors.forEach(err => showError(err));
        valid.forEach(file => uploadFile(file));
    });
}

function formatSize(bytes) {
    if (bytes < 1024) return `${bytes} B`;
    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
}

function showError(message) {
    const errorDiv = document.getElementById("upload-errors");
    errorDiv.innerHTML += `<p>${message}</p>`;
}

setupDropZone("drop-zone");

Subida con FormData y barra de progreso

El endpoint /api/upload debe procesar datos de formulario multipart — consulta validación de subida de archivos en Node.js para el lado del servidor.

function uploadFile(file) {
    const formData = new FormData();
    formData.append("file", file);

    const xhr = new XMLHttpRequest();
    const progressBar = createProgressBar(file.name);

    xhr.upload.addEventListener("progress", (e) => {
        if (e.lengthComputable) {
            const percent = Math.round((e.loaded / e.total) * 100);
            progressBar.style.width = `${percent}%`;
            progressBar.textContent = `${percent}%`;
        }
    });

    xhr.addEventListener("load", () => {
        if (xhr.status === 200) {
            console.log(`${file.name} subido correctamente`);
            progressBar.parentElement.classList.add("upload-complete");
        } else {
            console.error(`subida fallida de ${file.name}: ${xhr.status}`);
            progressBar.parentElement.classList.add("upload-error");
        }
    });

    xhr.addEventListener("error", () => {
        console.error(`error de subida en ${file.name}`);
        progressBar.parentElement.classList.add("upload-error");
    });

    xhr.open("POST", "/api/upload");
    xhr.send(formData);
    return xhr;
}

function createProgressBar(fileName) {
    const container = document.createElement("div");
    container.className = "upload-item";

    const label = document.createElement("span");
    label.textContent = fileName;

    const bar = document.createElement("div");
    bar.className = "progress-bar";

    const fill = document.createElement("div");
    fill.className = "progress-fill";

    bar.appendChild(fill);
    container.appendChild(label);
    container.appendChild(bar);
    document.getElementById("upload-list").appendChild(container);

    return fill;
}

Componente completo de subida drag and drop

class DragDropUploader {
    constructor(elementId, options = {}) {
        this.dropZone = document.getElementById(elementId);
        this.maxSize = options.maxSize ?? 5 * 1024 * 1024;
        this.allowedTypes = options.allowedTypes ?? ["image/jpeg", "image/png", "image/webp"];
        this.uploadUrl = options.uploadUrl ?? "/api/upload";
        this.onProgress = options.onProgress ?? (() => {});
        this.onComplete = options.onComplete ?? (() => {});
        this.onError = options.onError ?? (() => {});

        this.setupEvents();
    }

    setupEvents() {
        this.dropZone.addEventListener("dragover", (e) => {
            e.preventDefault();
            this.dropZone.classList.add("drag-over");
        });

        this.dropZone.addEventListener("dragleave", (e) => {
            if (!this.dropZone.contains(e.relatedTarget)) {
                this.dropZone.classList.remove("drag-over");
            }
        });

        this.dropZone.addEventListener("drop", (e) => {
            e.preventDefault();
            this.dropZone.classList.remove("drag-over");
            const files = Array.from(e.dataTransfer.files);
            this.handleFiles(files);
        });

        // También manejar click para explorar — teclado incluido
        this.dropZone.addEventListener("keydown", (e) => {
            if (e.key === "Enter" || e.key === " ") {
                e.preventDefault();
                this.dropZone.click();
            }
        });

        this.dropZone.addEventListener("click", () => {
            const input = document.createElement("input");
            input.type = "file";
            input.multiple = true;
            input.accept = this.allowedTypes.join(",");
            input.addEventListener("change", () => {
                this.handleFiles(Array.from(input.files));
            });
            input.click();
        });
    }

    handleFiles(files) {
        for (const file of files) {
            const error = this.validate(file);
            if (error) {
                this.onError(file, error);
                continue;
            }
            this.upload(file);
        }
    }

    validate(file) {
        if (!this.allowedTypes.includes(file.type)) {
            return `Tipo inválido: ${file.type}`;
        }
        if (file.size > this.maxSize) {
            return `Archivo demasiado grande: ${this.formatSize(file.size)}`;
        }
        return null;
    }

    upload(file) {
        const formData = new FormData();
        formData.append("file", file);

        const xhr = new XMLHttpRequest();

        xhr.upload.addEventListener("progress", (e) => {
            if (e.lengthComputable) {
                const percent = Math.round((e.loaded / e.total) * 100);
                this.onProgress(file, percent);
            }
        });

        xhr.addEventListener("load", () => {
            if (xhr.status === 200) {
                this.onComplete(file, JSON.parse(xhr.responseText));
            } else {
                this.onError(file, `Subida fallida: ${xhr.status}`);
            }
        });

        xhr.addEventListener("error", () => {
            this.onError(file, "Error de red");
        });

        xhr.open("POST", this.uploadUrl);
        xhr.send(formData);
    }

    formatSize(bytes) {
        if (bytes < 1024) return `${bytes} B`;
        if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
    }
}

// Uso
const uploader = new DragDropUploader("drop-zone", {
    maxSize: 10 * 1024 * 1024,
    allowedTypes: ["image/jpeg", "image/png", "image/webp", "application/pdf"],
    uploadUrl: "/api/upload",
    onProgress: (file, percent) => console.log(`${file.name}: ${percent}%`),
    onComplete: (file, response) => console.log(`${file.name} listo:`, response),
    onError: (file, error) => console.error(`${file.name}: ${error}`)
});

Código complementario: demo de subida ejecutable — esta clase conectada a una drop zone con estilos, barras de progreso y vistas previas de imagen, con un modo simulado que funciona sin backend.

Vista previa de imagen antes de subir

function previewImage(file) {
    if (!file.type.startsWith("image/")) return;

    const reader = new FileReader();

    reader.onload = (e) => {
        const img = document.createElement("img");
        img.src = e.target.result;
        img.style.maxWidth = "200px";
        img.style.maxHeight = "200px";
        img.style.borderRadius = "8px";

        const container = document.createElement("div");
        container.className = "preview-item";
        container.appendChild(img);

        const removeBtn = document.createElement("button");
        removeBtn.textContent = "Eliminar";
        removeBtn.onclick = () => container.remove();
        container.appendChild(removeBtn);

        document.getElementById("preview-grid").appendChild(container);
    };

    reader.readAsDataURL(file);
}

readAsDataURL mantiene el archivo completo en memoria como cadena base64 — aproximadamente un 33% más grande que el original. Para archivos grandes es mejor URL.createObjectURL(file), que devuelve una URL de blob ligera; recuerda llamar a URL.revokeObjectURL() cuando se quite la vista previa.

Filtrado de elementos y efecto de drop

Un drop no solo trae archivos — dataTransfer.items también puede contener texto o enlaces arrastrados, así que filtra por kind === "file" antes de leer nada. Y de paso, asigna e.dataTransfer.dropEffect dentro de dragover para controlar la pista del cursor ("copy" muestra el típico signo ”+”):

dropZone.addEventListener("dragover", (e) => {
    e.preventDefault();
    e.dataTransfer.dropEffect = "copy";
});

dropZone.addEventListener("drop", (e) => {
    e.preventDefault();
    const files = [];
    for (const item of e.dataTransfer.items) {
        if (item.kind === "file") files.push(item.getAsFile());
    }
    files.forEach(uploadFile);
});

Los navegadores basados en Chromium también exponen item.getAsFileSystemHandle(), que devuelve un FileSystemFileHandle de la File System Access API — úsala cuando necesites más que una lectura puntual, como guardar cambios en el mismo archivo. Para recorrer carpetas soltadas, webkitGetAsEntry() sigue siendo el camino multi-navegador.

Lectura de directorios soltados

La lista dataTransfer.files se queda en el nivel superior — suelta una carpeta y no verás lo que contiene. Para recorrer el contenido de una carpeta soltada, llama a webkitGetAsEntry() en cada DataTransferItem; funciona en todos los navegadores modernos — Chrome, Edge, Firefox y Safari:

dropZone.addEventListener("drop", (e) => {
    e.preventDefault();

    for (const item of e.dataTransfer.items) {
        const entry = item.webkitGetAsEntry();
        if (!entry) continue;

        if (entry.isFile) {
            entry.file(file => uploadFile(file));
        } else if (entry.isDirectory) {
            const reader = entry.createReader();
            const readBatch = () => {
                reader.readEntries(entries => {
                    if (entries.length === 0) return;
                    for (const child of entries) {
                        if (child.isFile) child.file(file => uploadFile(file));
                    }
                    readBatch(); // seguir leyendo: readEntries devuelve máx. 100 por llamada
                });
            };
            readBatch();
        }
    }
});

Cola de subidas y cancelación

Lanzar un XHR por cada archivo soltado funciona hasta que alguien suelta 50 de golpe — mantén 2-4 en vuelo y aparca el resto en una cola. El mismo map que registra las peticiones activas te regala abort() para cuando el usuario quita un archivo a mitad de subida:

const MAX_CONCURRENT = 3;
let inFlight = 0;
const queue = [];
const activeUploads = new Map(); // fileName -> XMLHttpRequest

function enqueueUpload(file) {
    queue.push(file);
    pumpQueue();
}

function pumpQueue() {
    while (inFlight < MAX_CONCURRENT && queue.length > 0) {
        const file = queue.shift();
        inFlight++;
        const xhr = uploadFile(file); // uploadFile devuelve el xhr
        activeUploads.set(file.name, xhr);
    }
}

// Dentro de los handlers load y error de uploadFile, libera el slot:
// inFlight--; activeUploads.delete(file.name); pumpQueue();

function cancelUpload(fileName) {
    const xhr = activeUploads.get(fileName);
    if (xhr) xhr.abort();
    activeUploads.delete(fileName);
    inFlight--;
    pumpQueue();
}

Conecta cancelUpload al botón de quitar en previewImage, y llama a enqueueUpload en vez de uploadFile dondequiera que recolectes archivos.

Explicación

La HTML5 Drag and Drop API funciona a través de una serie de eventos:

Flujo de eventos drag and drop: dragenter y dragover se repiten hasta drop o dragleave, luego los archivos pasan por validación antes de la subida FormData con eventos de progreso
  • dragenter se dispara cuando un elemento arrastrado entra en la drop zone — úsalo para la respuesta visual.
  • dragover se dispara continuamente sobre la zona, y llamar a e.preventDefault() en él es lo que realmente permite el drop.
  • dragleave se dispara cuando el elemento sale de la zona — es el momento de quitar el resaltado. También se dispara al mover el cursor sobre un elemento hijo, por eso los manejadores simples parpadean.
  • drop se dispara al soltar — llama otra vez a e.preventDefault() y saca los archivos de e.dataTransfer.files.

Puntos clave:

  • preventDefault() en dragover es la parte que todo el mundo olvida. Sin él el navegador trata el drop como una navegación de “abrir este archivo” en vez de entregarlo a tu manejador.
  • dataTransfer.files guarda los archivos soltados como un FileList; cada File dentro expone name, size, type y lastModified — el mismo objeto que te da un <input type="file">.
  • FormData + XHR para subidas: FormData se combina con fetch o XMLHttpRequest para el envío, pero solo XHR expone los eventos de progreso en upload — es la única característica que fetch todavía no tiene.
  • FileReader se encarga de leer contenidos en la página — readAsDataURL produce la cadena base64 detrás de las vistas previas de imagen, y readAsText es lo que quieres para archivos de texto plano.
  • Valida dos veces: comprueba file.type y file.size en el cliente para UX, y repite las validaciones en el servidor. file.type viene de la extensión y del sistema operativo, así que miente — un .exe renombrado puede aparecer como image/png. Para una verificación real, lee los primeros bytes (números mágicos) del archivo.
  • Limita la concurrencia: el navegador sube en paralelo sin problema, pero lanzar 50 XHR concurrentes congela la pestaña y satura el servidor. Encola las subidas y mantén 2-4 en vuelo a la vez.

Variantes

CaracterísticaMétodoUsar Cuando
Drop básicodataTransfer.filesSelección simple de archivos
ValidaciónVerificar tipo + tamañoApps en producción
Seguimiento de progresoXMLHttpRequest uploadSubidas de archivos grandes
Vista previa de imagenFileReader.readAsDataURLComponentes de subida de imágenes
Click + dragInput de archivo ocultoMejor UX
Drop de carpetawebkitGetAsEntryAceptar directorios
Pista del cursordropEffectArrastre con mejor respuesta
Handles de archivogetAsFileSystemHandleChromium, acceso lectura+escritura

Mejores Prácticas

  • Llama a e.preventDefault() tanto en dragover como en drop — omitir cualquiera rompe el drop silenciosamente.
  • Valida tipo y tamaño en el cliente para UX, y de nuevo en el servidor por seguridad.
  • Usa XMLHttpRequest cuando necesites eventos de progreso; fetch sirve para archivos pequeños donde el progreso no importa.
  • Da respuesta visual durante el arrastre — un borde, un resaltado o un icono que diga al usuario “suéltalo aquí”.
  • Combina siempre drag-and-drop con una alternativa de click para explorar; en móvil suele ser el único camino que funciona.
  • Haz que la zona sea alcanzable por teclado (role="button", tabindex="0", Enter/Espacio para explorar) y pon aria-live="polite" en la lista de errores para que los lectores de pantalla anuncien los rechazos.
  • Muestra una barra de progreso para cualquier cosa por encima de ~1 MB, para que el usuario no piense que la página se congeló.
  • Aborta XMLHttpRequest y FileReader pendientes cuando el usuario quita un archivo a mitad de subida.
  • Muestra errores del servidor con un mensaje sobre el que el usuario pueda actuar, no solo un console.error.

Errores Comunes

  • Omitir preventDefault() en dragover — el navegador entonces abre el archivo soltado en una pestaña nueva en vez de dejar que tu código lo maneje.
  • Confiar solo en file.type — viene de la extensión, así que no detiene a alguien que suelta un ejecutable renombrado.
  • Usar fetch cuando necesitas una barra de progreso; no tiene eventos de progreso de subida.
  • Quitar el resaltado en el primer dragleave — el evento también se dispara sobre elementos hijos. Compara e.relatedTarget o lleva un contador de enter/leave.
  • Agregar archivos a FormData con un nombre de campo que el backend no espera.
  • Publicar drag-and-drop sin alternativa de click — muchos usuarios nunca piensan en arrastrar un archivo a la página.

Lectura Adicional

Preguntas frecuentes

¿Cómo evito que el navegador abra el archivo al soltarlo fuera de la drop zone?

Suelta un archivo en cualquier punto fuera de la zona y el navegador navegará a él encantado. Protégete de eso con manejadores globales en window:

window.addEventListener("dragover", (e) => e.preventDefault());
window.addEventListener("drop", (e) => e.preventDefault());

Así evitas que el navegador secuestre la página cuando el usuario falla la drop zone.

¿Puedo usar fetch en vez de XMLHttpRequest para subidas?

Puedes — solo ten en cuenta que fetch no reporta progreso de subida. Cuando la barra de progreso no importa, esto es todo lo que necesitas:

const formData = new FormData();
formData.append("file", file);

const response = await fetch("/api/upload", {
    method: "POST",
    body: formData
});
¿Cómo manejo drag-and-drop en dispositivos móviles?

El drag and drop en móvil es limitado en el mejor de los casos, así que incluye siempre una alternativa de click para explorar con un <input type="file"> oculto. Si de verdad necesitas arrastre táctil, tendrías que construirlo tú mismo sobre la Touch Events API.

¿Cómo limito el número de archivos?

Verifica files.length en el manejador drop:

if (files.length > MAX_FILES) {
    showError(`Máximo ${MAX_FILES} archivos permitidos`);
    return;
}
¿Pueden los usuarios soltar una carpeta entera?

Sí, pero no a través de dataTransfer.files — ese objeto solo expone los archivos del nivel superior. Usa webkitGetAsEntry() en cada DataTransferItem y recorre los FileSystemDirectoryEntry recursivamente, como se muestra en Lectura de directorios soltados. El soporte es bueno en Chrome, Edge, Firefox y Safari, pero mantén siempre la alternativa del input de archivo para navegadores y dispositivos donde el drop de carpetas no funciona.