react-upload-kit

Headless, adapter-based file upload toolkit for React. Zero dependencies. Full TypeScript support.

Most upload libraries either ship opinionated UI that fights your design system, or leave you wiring up low-level browser APIs by hand. react-upload-kit gives you composable hooks and renderless components that handle the hard parts -- drag & drop, validation, concurrency, retry, cancellation, previews -- while you own 100% of the UI.

Features

Headless	Hooks-first API, zero styling opinions. You build the UI.
Adapter pattern	Bring your own upload function -- XHR, fetch, S3 presigned, tus.io, anything that returns a Promise.
Drag & drop	Native HTML5 DnD with real-time accept/reject feedback during drag.
Clipboard paste	Paste images directly from clipboard into any target element.
Validation	File size, MIME type, count limits, and custom validator functions.
Concurrency	Configurable parallel upload queue.
Retry	Automatic retry with exponential backoff.
Cancel	Abort in-flight uploads via AbortController.
Preview	Object URL image previews with optional resize and auto memory cleanup.
Components	Optional renderless components via react-upload-kit/components.
Tree-shakeable	Dual CJS/ESM, sideEffects: false. Import only what you use.
Typed	Generic TResponse flows end-to-end from adapter to file state.
Zero deps	Only react as a peer dependency.
Tested	127 tests across core, hooks, and components.

Installation

npm install react-upload-kit

Peer dependency: React 18 or later.

Quick Start

import { useUploader, useDropzone } from 'react-upload-kit';

const uploadAdapter = async (file, { onProgress, signal }) => {
  const formData = new FormData();
  formData.append('file', file);

  const xhr = new XMLHttpRequest();

  return new Promise((resolve, reject) => {
    signal.addEventListener('abort', () => xhr.abort());

    xhr.upload.addEventListener('progress', (e) => {
      if (e.lengthComputable) {
        onProgress(Math.round((e.loaded / e.total) * 100));
      }
    });

    xhr.addEventListener('load', () => {
      if (xhr.status >= 200 && xhr.status < 300) {
        resolve(JSON.parse(xhr.responseText));
      } else {
        reject(new Error(`Upload failed: ${xhr.status}`));
      }
    });

    xhr.addEventListener('error', () => reject(new Error('Network error')));
    xhr.open('POST', '/api/upload');
    xhr.send(formData);
  });
};

function FileUploader() {
  const uploader = useUploader({
    adapter: uploadAdapter,
    accept: ['image/*', '.pdf'],
    maxFileSize: 10 * 1024 * 1024,
    maxFiles: 5,
    autoUpload: true,
    concurrency: 3,
    maxRetries: 2,
  });

  const dropzone = useDropzone({
    onDrop: uploader.addFiles,
    accept: ['image/*', '.pdf'],
  });

  return (
    <div>
      <div {...dropzone.getRootProps()}>
        <input {...dropzone.getInputProps()} />
        {dropzone.isDragActive
          ? 'Drop files here...'
          : 'Drag & drop files, or click to select'}
      </div>

      {uploader.files.map((file) => (
        <div key={file.id}>
          <span>{file.file.name}</span>
          <span>{file.progress}%</span>
          <span>{file.status}</span>
          {file.status === 'uploading' && (
            <button onClick={() => uploader.cancelFile(file.id)}>Cancel</button>
          )}
          {file.status === 'error' && (
            <button onClick={() => uploader.retryFile(file.id)}>Retry</button>
          )}
          <button onClick={() => uploader.removeFile(file.id)}>Remove</button>
        </div>
      ))}
    </div>
  );
}

Exports

The package has two entrypoints:

// Hooks, core utilities, and types
import { useUploader, useDropzone, usePaste, useFilePreview } from 'react-upload-kit';

// Optional renderless components
import { Dropzone, FileList, UploadTrigger } from 'react-upload-kit/components';

API Reference

useUploader<TResponse>(options)

The main orchestrator hook. Manages file state, validation, upload queue, and lifecycle callbacks.

Options:

Option	Type	Default	Description
adapter	UploadAdapter<TResponse>	required	Upload function
accept	string[]	--	Accepted MIME types or extensions ('image/*', '.pdf')
maxFileSize	number	--	Max file size in bytes
minFileSize	number	--	Min file size in bytes
maxFiles	number	--	Max number of files
autoUpload	boolean	false	Start upload immediately when files are added
concurrency	number	3	Max parallel uploads
maxRetries	number	0	Max retry attempts per file
retryDelay	number	1000	Base retry delay in ms (exponential backoff)
validator	FileValidator	--	Custom validation function
onFileAdded	(file) => void	--	Called when a file is added
onFileRemoved	(file) => void	--	Called when a file is removed
onUploadStart	(file) => void	--	Called when upload begins
onUploadProgress	(file, percent) => void	--	Called on progress update
onUploadSuccess	(file, response) => void	--	Called on successful upload
onUploadError	(file, error) => void	--	Called on upload failure
onAllComplete	() => void	--	Called when all uploads finish

Returns:

Property	Type	Description
files	UploadFile<TResponse>[]	Current file list with state
addFiles	(files: File[]) => void	Add files (triggers validation)
removeFile	(id: string) => void	Remove a file
upload	() => void	Start uploading all pending files
retryFile	(id: string) => void	Retry a failed/cancelled file
retryAll	() => void	Retry all failed/cancelled files
cancelFile	(id: string) => void	Cancel an in-flight upload
cancelAll	() => void	Cancel all in-flight uploads
clearCompleted	() => void	Remove successfully uploaded files
clearAll	() => void	Cancel everything and clear
isUploading	boolean	Whether any file is currently uploading
totalProgress	number	Average progress across all files (0-100)
rejections	FileRejection[]	Most recent batch of rejected files

---

useDropzone(options)

Drag & drop zone hook with prop-getter pattern.

Options:

Option	Type	Default	Description
onDrop	(files: File[]) => void	required	Called with accepted files
onDropRejected	(rejections) => void	--	Called with rejected files
accept	string[]	--	Accepted file types
multiple	boolean	true	Allow multiple files
disabled	boolean	false	Disable the dropzone
noClick	boolean	false	Disable click-to-select
noDrag	boolean	false	Disable drag & drop
maxFiles	number	--	Max file count
maxFileSize	number	--	Max file size
minFileSize	number	--	Min file size
validator	FileValidator	--	Custom validator

Returns:

Property	Type	Description
getRootProps	(props?) => props	Spread on the container element
getInputProps	(props?) => props	Spread on a hidden <input>
isDragActive	boolean	Files are being dragged over
isDragAccept	boolean	Dragged files match accept criteria
isDragReject	boolean	Dragged files don't match
open	() => void	Programmatically open file dialog

---

usePaste(options)

Clipboard paste support.

usePaste({
  onPaste: uploader.addFiles,
  accept: ['image/*'],
  enabled: true,
  targetRef: containerRef, // optional, defaults to document
});

---

useFilePreview(file, options?)

Object URL preview generation with automatic cleanup.

const { previewUrl, isLoading } = useFilePreview(uploadFile.file, {
  maxWidth: 200,
  maxHeight: 200,
  enabled: true,
});

Returns { previewUrl: string | null, isLoading: boolean }. The URL is revoked automatically on unmount or when the file changes.

---

Components

Optional renderless components for a declarative API. Import from react-upload-kit/components:

<Dropzone>

<Dropzone onDrop={uploader.addFiles} accept={['image/*']}>
  {({ getRootProps, getInputProps, isDragActive }) => (
    <div {...getRootProps()}>
      <input {...getInputProps()} />
      {isDragActive ? 'Drop here!' : 'Drag & drop or click'}
    </div>
  )}
</Dropzone>

<FileList>

<FileList
  files={uploader.files}
  onRemove={uploader.removeFile}
  onRetry={uploader.retryFile}
  onCancel={uploader.cancelFile}
>
  {({ file, preview, remove, retry, cancel }) => (
    <div key={file.id}>
      {preview && <img src={preview} alt={file.file.name} />}
      <span>{file.file.name}</span>
      <progress value={file.progress} max={100} />
      <button onClick={remove}>Remove</button>
      {file.status === 'error' && <button onClick={retry}>Retry</button>}
      {file.status === 'uploading' && <button onClick={cancel}>Cancel</button>}
    </div>
  )}
</FileList>

<UploadTrigger>

<UploadTrigger onSelect={uploader.addFiles} accept={['image/*']}>
  {({ open, inputProps }) => (
    <>
      <button onClick={open}>Select Files</button>
      <input {...inputProps} />
    </>
  )}
</UploadTrigger>

---

Upload Adapter

The adapter is a function you provide. It receives a File and a context object:

type UploadAdapter<TResponse> = (
  file: File,
  context: {
    onProgress: (percent: number) => void;
    signal: AbortSignal;
  },
) => Promise<TResponse>;

Call onProgress with a 0-100 value to report progress. Respect signal for cancellation support.

Minimal fetch adapter:

const fetchAdapter = async (file, { signal }) => {
  const body = new FormData();
  body.append('file', file);
  const res = await fetch('/api/upload', { method: 'POST', body, signal });
  if (!res.ok) throw new Error(`Upload failed: ${res.status}`);
  return res.json();
};

fetch() does not support upload progress. Use XMLHttpRequest if you need it. See the XHR adapter example above.

---

File States

pending -> uploading -> success
                     -> error     -> (retry) -> uploading
                     -> cancelled -> (retry) -> uploading

Each UploadFile object contains:

interface UploadFile<TResponse> {
  id: string;
  file: File;
  status: 'pending' | 'uploading' | 'success' | 'error' | 'cancelled';
  progress: number;       // 0-100
  error: Error | null;
  response: TResponse | null;
  retryCount: number;
}

Custom Validation

Return a FileError (or array) to reject, or null to accept:

const noSpaces = (file) => {
  if (file.name.includes(' ')) {
    return { code: 'validation-error', message: 'Filename must not contain spaces' };
  }
  return null;
};

const uploader = useUploader({
  adapter: myAdapter,
  validator: noSpaces,
});

Development

git clone https://github.com/batuhan/react-upload-kit.git
cd react-upload-kit
npm install
npm test

Script	Description
npm test	Run test suite
npm run test:watch	Run tests in watch mode
npm run typecheck	TypeScript type check
npm run build	Production build (CJS + ESM + .d.ts)
npm run dev	Watch mode build

Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feat/my-feature)
3. Make sure tests pass (npm test) and add tests for new functionality
4. Commit your changes (git commit -m 'feat: add my feature')
5. Push to the branch (git push origin feat/my-feature)
6. Open a Pull Request

Guidelines

• All new features and bug fixes must include tests.
• Follow the existing code style (TypeScript strict mode, no any).
• Keep the library headless -- no UI opinions, no CSS.
• Maintain backward compatibility unless there's a major version bump.

License

MIT