📤 Headless File Uploader

A powerful, flexible, and completely headless file upload library for applications. Built with TypeScript, zero dependencies, and designed to work with any UI framework or design system.

✨ Features

• 🎯 Completely Headless - No UI components, just pure logic and state management
• 📁 Multi-File Upload - Effortlessly handle single or multiple files simultaneously
• 🎨 Framework Agnostic - Provides stable, isolated wrappers for React, Vue, Svelte, Angular, Solid, Qwik, Lit, and jQuery
• 📊 Real-time Progress - Precise tracking with speed (bps) and time remaining estimates
• 🧩 Chunked Upload - Intelligent large file splitting with concurrent chunk processing
• ⏸️ Pause & Resume - Full control over the upload lifecycle at any moment
• 🔁 Auto Retry - Robust error handling with customizable exponential backoff
• 🖼️ Preview Generation - Built-in high-performance preview generation for images and videos
• 📋 Metadata Extraction - Automatically extract dimensions, duration, and extended file metadata
• ☁️ Cloud Ready - Flexible adapter pattern for AWS S3, Google Cloud, Azure, and more: TBD
• 🗜️ Smart Compression - Optional client-side image compression before transfer
• ✅ Advanced Validation - Deep validation for MIME types, extensions, size, and custom logic
• 🎭 TypeScript First - 100% type safety and excellent IntelliSense support
• 🌳 Tree Shakeable - Import only what you need, keeping bundles tiny
• 📦 Zero Dependencies - Highly secure, fast, and completely self-contained core engine

🚀 Installation

Install the relevant library for use in available framework.

Framework	Package Name	Installation Command
Vanilla	@verbpatch/headless-uploader	npm install @verbpatch/headless-uploader
React	@verbpatch/react-uploader	npm install @verbpatch/react-uploader
Svelte	@verbpatch/svelte-uploader	npm install @verbpatch/svelte-uploader
Vuejs	@verbpatch/vue-uploader	npm install @verbpatch/vue-uploader
jQuery	@verbpatch/jquery-uploader	npm install @verbpatch/jquery-uploader
Angular	@verbpatch/angular-uploader	npm install @verbpatch/angular-uploader
Lit	@verbpatch/lit-uploader	npm install @verbpatch/lit-uploader
Preact	@verbpatch/preact-uploader	npm install @verbpatch/preact-uploader
Qwik	@verbpatch/qwik-uploader	npm install @verbpatch/qwik-uploader
SolidJs	@verbpatch/solid-uploader	npm install @verbpatch/solid-uploader

🪁 Basic Javascript/Typescript Example

import { useUploader } from "@verbpatch/headless-uploader";

const uploader = useUploader({
  http: {
    endpoint: "/api/upload",
  },
  autoUpload: true,
  onUploadProgress: (file, progress) => {
    console.log(`${file.metadata.name}: ${progress.percentage}%`);
  },
});

// Bind to a file input
const input = document.getElementById('my-input');
input.addEventListener('change', (e) => uploader.handleFileSelect(e));

// Or handle drag & drop
const dropzone = document.getElementById('dropzone');
dropzone.addEventListener('dragover', (e) => uploader.handleDragOver(e));
dropzone.addEventListener('drop', (e) => uploader.handleDrop(e));

🎨 Basic React Example

import { useUploader } from "@verbpatch/react-uploader";

function MyUploader() {
  const uploader = useUploader({
    http: { endpoint: "/api/upload" },
    maxFiles: 5,
    onUploadSuccess: (file, response) => {
      console.log('Upload finished!', response);
    }
  });

  const state = uploader.getState();

  return (
    <div>
      <div 
        onDrop={uploader.handleDrop} 
        onDragOver={uploader.handleDragOver}
        style={{ border: '2px dashed #ccc', padding: '20px' }}
      >
        Drop files here or <input type="file" onChange={uploader.handleFileSelect} multiple />
      </div>

      <ul>
        {state.files.map(file => (
          <li key={file.id}>
            {file.metadata.name} - {file.status} 
            ({file.progress.percentage.toFixed(1)}%)
            <button onClick={() => uploader.cancelUpload(file.id)}>Cancel</button>
          </li>
        ))}
      </ul>
    </div>
  );
}

🔗 Helpful Links

• Documentation
• Examples
• Issues
• Contributing Guide
• Changelog