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:
dragenterse dispara cuando un elemento arrastrado entra en la drop zone — úsalo para la respuesta visual.dragoverse dispara continuamente sobre la zona, y llamar ae.preventDefault()en él es lo que realmente permite el drop.dragleavese 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.dropse dispara al soltar — llama otra vez ae.preventDefault()y saca los archivos dee.dataTransfer.files.
Puntos clave:
preventDefault()endragoveres 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.filesguarda los archivos soltados como unFileList; cadaFiledentro exponename,size,typeylastModified— el mismo objeto que te da un<input type="file">.- FormData + XHR para subidas:
FormDatase combina confetchoXMLHttpRequestpara el envío, pero solo XHR expone los eventos de progreso enupload— es la única característica quefetchtodavía no tiene. - FileReader se encarga de leer contenidos en la página —
readAsDataURLproduce la cadena base64 detrás de las vistas previas de imagen, yreadAsTextes lo que quieres para archivos de texto plano. - Valida dos veces: comprueba
file.typeyfile.sizeen el cliente para UX, y repite las validaciones en el servidor.file.typeviene de la extensión y del sistema operativo, así que miente — un.exerenombrado puede aparecer comoimage/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ística | Método | Usar Cuando |
|---|---|---|
| Drop básico | dataTransfer.files | Selección simple de archivos |
| Validación | Verificar tipo + tamaño | Apps en producción |
| Seguimiento de progreso | XMLHttpRequest upload | Subidas de archivos grandes |
| Vista previa de imagen | FileReader.readAsDataURL | Componentes de subida de imágenes |
| Click + drag | Input de archivo oculto | Mejor UX |
| Drop de carpeta | webkitGetAsEntry | Aceptar directorios |
| Pista del cursor | dropEffect | Arrastre con mejor respuesta |
| Handles de archivo | getAsFileSystemHandle | Chromium, acceso lectura+escritura |
Mejores Prácticas
- Llama a
e.preventDefault()tanto endragovercomo endrop— 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
XMLHttpRequestcuando necesites eventos de progreso;fetchsirve 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 ponaria-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
XMLHttpRequestyFileReaderpendientes 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()endragover— 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
fetchcuando 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. Comparae.relatedTargeto lleva un contador de enter/leave. - Agregar archivos a
FormDatacon 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.
Recursos Relacionados
Validación de Subida de Archivos
Cómo manejar subidas de archivos de forma segura con validación de tamaño, tipo y contenido.
RecipeValidación de Subidas en Node.js: Tipo, Tamaño y Contenido
Valida subidas de archivos en Node.js con multer — límites de tamaño, verificación de MIME, magic bytes y escaneo de virus para APIs Express.
RecipeComprimir y Descomprimir Archivos con ZIP, GZIP y TAR
Crea y extrae archivos ZIP, GZIP y TAR en Python, Node.js, Java y Bash con lectura en streaming y patrones de extracción segura.
RecipeCopiar y Pegar con Clipboard en JavaScript
Copia y pega texto, HTML e imágenes en JavaScript con la Clipboard API: reglas de contexto seguro, fallback con execCommand y quirks reales de cada navegador
RecipeLocalStorage con Expiración TTL en JavaScript
Almacena datos en localStorage con expiración TTL: limpieza perezosa, manejo de cuota, stale-while-revalidate y sincronización entre pestañas
RecipePaginación con Scroll Infinito en JavaScript
Implementa carga de datos por scroll en JavaScript con IntersectionObserver: detección por centinela, fetch, estados de carga y error, y limpieza correcta.