Skip to main content

Getting Started with Dropup

Dropup is a lightweight, headless React file upload library that gives you complete control over your UI while handling all the complex upload logic.

Why Dropup?​

  • 🪶 Lightweight - Core is only ~10KB gzipped
  • 🎨 Headless - Full control over your UI with hooks-based API
  • 📁 Drag & Drop - Built-in drag-and-drop support
  • 📊 Progress Tracking - Real-time upload progress for each file
  • 🔄 Chunked Uploads - Split large files for reliable uploads
  • ☁️ Cloud Ready - Pre-built helpers for S3, GCS, and Azure
  • 🖼️ Image Processing - Built-in compression and preview generation
  • 📱 Cross-Platform - Works with React DOM and React Native
  • 🔒 TypeScript - Full TypeScript support

Installation​

Install Dropup using your preferred package manager:

npm install @samithahansaka/dropup

Peer Dependencies​

Dropup requires React 16.8 or higher (for hooks support):

npm install react

Quick Start​

Here's a simple example to get you started:

import { useDropup } from '@samithahansaka/dropup';

function FileUploader() {
  const {
    files,
    state,
    actions,
    getDropProps,
    getInputProps
  } = useDropup({
    accept: 'image/*',
    maxSize: 10 * 1024 * 1024, // 10MB
    multiple: true,
  });

  return (
    <div>
      {/* Drop zone */}
      <div
        {...getDropProps()}
        style={{
          border: state.isDragging ? '2px dashed blue' : '2px dashed gray',
          padding: 40,
          textAlign: 'center',
          cursor: 'pointer',
        }}
      >
        <input {...getInputProps()} />
        <p>Drag & drop files here, or click to select</p>
      </div>

      {/* File list */}
      <ul>
        {files.map((file) => (
          <li key={file.id}>
            {file.name} - {file.status}
            {file.status === 'uploading' && ` (${file.progress}%)`}
            <button onClick={() => actions.remove(file.id)}>Remove</button>
          </li>
        ))}
      </ul>

      {/* Upload button */}
      {files.length > 0 && (
        <button onClick={() => actions.upload()}>
          Upload All
        </button>
      )}
    </div>
  );
}

Core Concepts​

1. The useDropup Hook​

The useDropup hook is the main entry point. It returns everything you need to build your file upload UI:

const {
  files,           // Array of files with status, progress, etc.
  state,           // Overall state (isDragging, isUploading, progress)
  actions,         // Methods to upload, remove, cancel, reset
  getDropProps,    // Props for your drop zone element
  getInputProps,   // Props for the hidden file input
} = useDropup(options);

2. File Objects​

Each file in the files array contains:

{
  id: string;          // Unique identifier
  file: File;          // Original File object
  name: string;        // File name
  size: number;        // File size in bytes
  type: string;        // MIME type
  preview?: string;    // Preview URL (for images)
  status: 'idle' | 'uploading' | 'complete' | 'error';
  progress: number;    // Upload progress (0-100)
  error?: Error;       // Error object if upload failed
  uploadedUrl?: string; // URL after successful upload
}

3. Actions​

The actions object provides methods to control uploads:

actions.upload(fileIds?)    // Start uploading (all or specific files)
actions.cancel(fileId?)     // Cancel upload(s)
actions.remove(fileId)      // Remove a file from the list
actions.reset()             // Clear all files
actions.retry(fileIds?)     // Retry failed uploads

Configuring Uploads​

To enable actual uploads, provide an upload configuration:

const { files } = useDropup({
  upload: {
    url: '/api/upload',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer token',
    },
  },
  autoUpload: true, // Upload automatically when files are added
});

Next Steps​