hcg-file-drop

A lightweight, zero-dependency JavaScript drag-and-drop file upload widget. Drop files onto a zone or click to browse, with type filtering, a file-count limit, duplicate detection, an optional removable file list, and a disabled state.

• npm: npmjs.com/package/hcg-file-drop
• Documentation & demo: html-code-generator.com/javascript/file-drop-library
• React demo: StackBlitz

Features

• Zero dependencies: one JavaScript file and a companion CSS stylesheet
• Drag and drop or click to browse
• Type filtering by MIME type, wildcard, or file extension
• Configurable file limit and duplicate detection
• Optional removable file list
• disable(), enable(), reset(), and destroy() instance API
• TypeScript definitions included

Demo

Use the Documentation & demo link above for the live interactive demo on the website.

After cloning this repository, open index.html in your browser for a local demo.

Installation

Download

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

npm

npm install hcg-file-drop

import hcgFileDrop from "hcg-file-drop";
import "hcg-file-drop/hcg-file-drop.css";

CDN

<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>

Quick start

<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: (files) => console.log(files),
    }
  );
</script>

Getting files

The widget does not upload automatically. Read the current list with getFiles(), or use the onFilesChange callback when files are added or removed.

const files = uploader.getFiles();

files.forEach((entry) => {
  console.log(entry.name, entry.type, entry.size);
  // entry.file is the original File object
});

Each entry has this shape:

{
  file,   // original File object
  name,   // file name
  type,   // MIME type
  size    // size in bytes
}

Uploading files

Append each entry.file to FormData and send with fetch when you are ready:

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

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

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

React

Create the widget inside useEffect against a ref element and call destroy() on unmount. See the StackBlitz React demo in this project's stackblitz-react/ folder.

License

MIT - HTML Code Generator