@stack-upload-orchestrator/react

React hook and components for file uploads — powered by @stack-upload-orchestrator/core.

Installation

npm install @stack-upload-orchestrator/react @stack-upload-orchestrator/core

Requires React ≥ 18.

Quick start

import { useUploadium } from '@stack-upload-orchestrator/react';

function Uploader() {
  const { upload, files, progress, isUploading } = useUploadium({
    endpoint: '/api/upload',
    validation: { maxFileSize: '10MB', allowedTypes: ['image/*'] },
  });

  return (
    <div>
      <input type="file" multiple onChange={(e) => upload(e.target.files!)} />
      {isUploading && <p>Uploading… {progress}%</p>}
      {files.map((f) => (
        <div key={f.id}>{f.name} — {f.status}</div>
      ))}
    </div>
  );
}

useUploadium

const result = useUploadium(options?: UseUploadiumOptions)

Options

| Option | Type | Description | |---|---|---| | endpoint | string | REST endpoint to POST files to. Auto-creates an XHR uploader with progress tracking. | | headers | Record<string, string> | HTTP headers sent with every request when using endpoint. | | uploader | Uploader | Custom uploader function. Takes precedence over endpoint. | | concurrency | number | Max simultaneous uploads. Default: 3 | | autoStart | boolean | Start uploading immediately on add. Default: true | | validation | ValidationOptions | File validation rules (size, type, extension, count). | | retry | RetryOptions | Retry configuration with exponential backoff. |

Return value

| Property | Type | Description | |---|---|---| | files | UploadTask[] | All tasks currently in the queue | | upload | (files, options?) => UploadTask[] | Add files and start uploading | | cancel | (taskId?) => void | Cancel one task or all | | pause | (taskId?) => void | Pause one task or the whole queue | | resume | (taskId?) => void | Resume one task or the whole queue | | retry | (taskId?) => void | Retry failed task(s) | | remove | (taskId) => void | Remove a task from the queue | | clear | () => void | Remove all tasks | | progress | number | Aggregate progress 0–100 | | isUploading | boolean | Whether any task is currently uploading | | isPaused | boolean | Whether the queue is paused | | queue | UploadQueue | Direct access to the underlying queue for advanced use |

Components

<UploadDropzone>

Drag-and-drop upload zone.

import { UploadDropzone } from '@stack-upload-orchestrator/react';

<UploadDropzone
  endpoint="/api/upload"
  onUploadComplete={(results) => console.log(results)}
  validation={{ maxFileSize: '10MB', allowedTypes: ['image/*'] }}
/>

<UploadButton>

A button that opens a file picker.

import { UploadButton } from '@stack-upload-orchestrator/react';

<UploadButton
  endpoint="/api/upload"
  onUploadComplete={(results) => console.log(results)}
/>

<UploadList>

Renders the current queue state — file names, statuses, and progress bars.

import { useUploadium, UploadList } from '@stack-upload-orchestrator/react';

function Uploader() {
  const uploader = useUploadium({ endpoint: '/api/upload' });
  return <UploadList uploader={uploader} />;
}

createFetchUploader

Creates an XHR-based uploader that reports real upload progress. Used internally by useUploadium when you pass endpoint, but also available for custom setups.

import { createFetchUploader } from '@stack-upload-orchestrator/react';
import { UploadQueue } from '@stack-upload-orchestrator/core';

const uploader = createFetchUploader('/api/upload', {
  headers: { Authorization: 'Bearer token' },
  fieldName: 'file', // FormData field name, default: "file"
});

const queue = new UploadQueue({ uploader });

fetch() does not expose upload progress, so createFetchUploader uses XHR under the hood.

License

MIT