Lightweight JavaScript Drag & Drop File Upload Library

Drop files onto the zone below or click to browse. Accepted types: image/*, .pdf, .txt, .json. Maximum 5 files. Duplicates are skipped. Use Reset to clear the list or Disable to toggle the disabled state. For every option on one page, open the hcg-file-drop demo page.

How hcg-file-drop compares with common alternatives.

Choose hcg-file-drop when you want a tiny vanilla widget that collects File objects and leaves upload logic to your app. Use a heavier plugin when you need chunked uploads, cloud storage adapters, or a full UI framework out of the box.

Everything included in the library at a glance:

• Zero dependencies - one small JavaScript file and a companion CSS file.
• Script tag or bundler - works with a plain script tag, CommonJS, or ESM.
• Drag and drop or click to browse - both input methods work out of the box.
• Type filtering - accept exact MIME types, wildcards, or file extensions.
• Single or multiple - allow many files or restrict to one with the multiple option.
• File limit - cap the number of files held at once (default 10).
• Append or replace - keep previous files on each new drop, or replace them with replaceOnDrop.
• Duplicate detection - files with the same name and size are skipped.
• Optional file list - render a removable list below the drop zone or in a custom target.
• Disabled state - start disabled, or toggle at runtime with disable() and enable().
• Accessible - focusable zone with Enter and Space support.
• Multiple instances - independent widgets on the same page.
• TypeScript - definitions ship with the package.
• React-friendly - create in useEffect and call destroy() on unmount.

Direct download

Source code and package:

GitHub npm JavaScript (hcg-file-drop.js) CSS (hcg-file-drop.css)

Download hcg-file-drop.js and hcg-file-drop.css, then include both on your page:

HTML

<link rel="stylesheet" href="hcg-file-drop.css">
<script src="hcg-file-drop.js"></script>

npm

Install from npm:

Bash

npm install hcg-file-drop

CommonJS (require):

JavaScript

const hcgFileDrop = require("hcg-file-drop");
// also load hcg-file-drop.css however your bundler handles CSS

ESM (import):

JavaScript

import hcgFileDrop from "hcg-file-drop";

CDN usage

Load from a CDN with one script and one stylesheet - no npm or bundler required. The global hcgFileDrop function is available as soon as the script finishes loading.

jsDelivr:

HTML

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/hcg-file-drop@1/hcg-file-drop.css">
<script src="https://cdn.jsdelivr.net/npm/hcg-file-drop@1/hcg-file-drop.js"></script>

unpkg:

HTML

<link rel="stylesheet" href="https://unpkg.com/hcg-file-drop@1/hcg-file-drop.css">
<script src="https://unpkg.com/hcg-file-drop@1/hcg-file-drop.js"></script>

Replace @1 or @1.0.0 with the release you want. You can also self-host by uploading hcg-file-drop.js and hcg-file-drop.css to your own server.

Install hcg-file-drop, add a container element, and pass an options object. The widget renders itself inside the element and returns an instance you can call later.

Initialize the widget

Pass a container element and options. The drop zone and optional file list are injected automatically.

HTML

<link rel="stylesheet" href="hcg-file-drop.css">
<div id="upload-container"></div>

<script src="hcg-file-drop.js"></script>
<script>
  const uploader = hcgFileDrop(
    document.getElementById('upload-container'),
    {
      allowedTypes: ['image/*', '.pdf', '.txt', '.json'],
      maxFiles: 5,
      showFileList: true,
      onFilesChange: function (files) {
        console.log(files);
      }
    }
  );
</script>

File entry shape

Each entry passed to onFilesChange and returned from getFiles() has this shape:

JavaScript

{
  file,   // the original File object
  name,   // file name
  type,   // MIME type reported by the browser
  size    // size in bytes
}

The original File object is kept on the file property, so you can upload it yourself with FormData and fetch whenever you are ready.

Instance methods

Store the returned instance and call its methods whenever you need them.

JavaScript

const files = uploader.getFiles();
uploader.reset();
uploader.disable();
uploader.isDisabled(); // true
uploader.enable();
uploader.destroy();
console.log(hcgFileDrop.version);

The widget does not upload by itself. Read files with getFiles(), append each entry.file to a FormData, and send it to your server.

Using fetch

JavaScript

function uploadFiles() {
  const files = uploader.getFiles();
  if (files.length === 0) return;

  const formData = new FormData();
  files.forEach(function (entry) {
    formData.append('files[]', entry.file, entry.name);
  });

  fetch('/upload', { method: 'POST', body: formData })
    .then(function (res) {
      if (!res.ok) throw new Error('Upload failed: ' + res.status);
      return res.json();
    })
    .then(function (data) {
      console.log('Upload complete', data);
      uploader.reset();
    })
    .catch(function (err) {
      console.error(err);
    });
}

Using XMLHttpRequest

Use XMLHttpRequest when you need an upload progress indicator.

JavaScript

function uploadFilesAjax() {
  const files = uploader.getFiles();
  if (files.length === 0) return;

  const formData = new FormData();
  files.forEach(function (entry) {
    formData.append('files[]', entry.file, entry.name);
  });

  const xhr = new XMLHttpRequest();
  xhr.open('POST', '/upload', true);

  xhr.upload.onprogress = function (e) {
    if (e.lengthComputable) {
      const percent = Math.round((e.loaded / e.total) * 100);
      console.log('Uploaded ' + percent + '%');
    }
  };

  xhr.onload = function () {
    if (xhr.status >= 200 && xhr.status < 300) {
      console.log('Upload complete', xhr.responseText);
      uploader.reset();
    } else {
      console.error('Upload failed: ' + xhr.status);
    }
  };

  xhr.onerror = function () {
    console.error('Network error during upload');
  };

  xhr.send(formData);
}

Both examples send all files in one request under the files[] field. To upload a single file, append just files[0].file instead.

Import hcgFileDrop from the package and create the widget inside useEffect. Call destroy() in the cleanup function when the component unmounts.

Try the live React demo on StackBlitz

Uploader component

JavaScript

import { useEffect, useRef } from "react";
import hcgFileDrop from "hcg-file-drop";
import "hcg-file-drop/hcg-file-drop.css";

function Uploader({ onFilesChange }) {
  const ref = useRef(null);

  useEffect(() => {
    const instance = hcgFileDrop(ref.current, {
      allowedTypes: ['image/*', '.pdf'],
      maxFiles: 5,
      showFileList: true,
      onFilesChange
    });
    return () => instance.destroy();
  }, [onFilesChange]);

  return <div ref={ref}></div>;
}

export default Uploader;

Load hcg-file-drop.css once in your app entry or import it in the component. Use disable() and enable() from props or effects when you need to lock the widget during async work.

Create as many drop zones on a page as you need. Each call to hcgFileDrop() returns a fully independent instance with its own files, options, event listeners, and API.

<link rel="stylesheet" href="hcg-file-drop.css">

<div id="avatars"></div>
<div id="documents"></div>

<script src="hcg-file-drop.js"></script>
<script>
  const avatars = hcgFileDrop(document.getElementById('avatars'), {
    allowedTypes: ['image/*'],
    maxFiles: 1,
    showFileList: true,
    onFilesChange: function (files) { console.log('avatar:', files); }
  });

  const docs = hcgFileDrop(document.getElementById('documents'), {
    allowedTypes: ['.pdf', '.docx'],
    maxFiles: 10,
    showFileList: true,
    onFilesChange: function (files) { console.log('docs:', files); }
  });

  // avatars.disable();
  // docs.getFiles();
</script>

• If you use fileListTarget, give each instance a different target element.
• preventWindowDrop acts page-wide, so you only need it on one instance.
• Call each instance's destroy() when removing it from the DOM.

All default styles live in hcg-file-drop.css, using plain single-class selectors. Edit that file directly, or override any rule from your own stylesheet loaded after it.

• .hcg-dragdrop-zone - the drop zone (.hcg-dragdrop-zone--active while dragging over, .hcg-dragdrop-zone--disabled when disabled)
• .hcg-dragdrop-hint - the hint text inside the zone
• .hcg-dragdrop-input - the hidden file input
• .hcg-dragdrop-list / .hcg-dragdrop-item - the optional file list and its rows
• .hcg-dragdrop-name, .hcg-dragdrop-meta, .hcg-dragdrop-remove - parts of each row

.hcg-dragdrop-zone { border-color: #10b981; background: #ecfdf5; }
.hcg-dragdrop-zone--active { border-color: #059669; }
.hcg-dragdrop-item { border-radius: 6px; }

Pass these as the second argument to hcgFileDrop(element, options).

Duplicate files (same name and size) are skipped automatically.

hcgFileDrop(element, options) returns an instance with these methods. The factory also exposes hcgFileDrop.version.

onFilesChange callback

The widget reports changes through onFilesChange rather than custom DOM events. It fires when files are added by drop or browse, when a file is removed, and when reset() clears the list.

JavaScript

hcgFileDrop(container, {
  onFilesChange: function (files) {
    if (files.length === 0) {
      console.log('No files selected');
      return;
    }
    files.forEach(function (f) {
      console.log(f.name, f.type, f.size);
    });
  }
});

The drop zone is a focusable role="button" element with an aria-label. Users can press Enter or Space to open the file browser. When disabled, aria-disabled is set and the zone is removed from the tab order.

Pair the widget with visible labels and error messages so users know which files are accepted and what happens after selection. Do not rely on drag-and-drop alone for critical workflows.

Works in all modern browsers that support the File and Drag-and-Drop APIs, including the latest versions of Chrome, Firefox, Safari, and Edge. No polyfills are required.

Released under the MIT License. Free for personal and commercial use. Copyright HTML Code Generator.