useUploader

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

function useUploader<TResponse = unknown>(
  options: UploaderOptions<TResponse>,
): UploaderInstance<TResponse>

Options

Option	Type	Default	Description
adapter	UploadAdapter<TResponse>	required	Upload function
accept	string[]	—	MIME types or extensions ('image/*', '.pdf')
maxFileSize	number	—	Max size in bytes
minFileSize	number	—	Min size in bytes
maxFiles	number	—	Max number of files (includes already added)
autoUpload	boolean	false	Enqueue as soon as files are added
concurrency	number	3	Max parallel adapter calls
maxRetries	number	0	Automatic retries per file
retryDelay	number	1000	Base delay in ms; exponential backoff
validator	FileValidator	—	Custom validation
onFileAdded	(file) => void	—	File accepted into state
onFileRemoved	(file) => void	—	After removeFile
onUploadStart	(file) => void	—	Adapter starting
onUploadProgress	(file, percent) => void	—	Progress tick
onUploadSuccess	(file, response) => void	—	Adapter resolved
onUploadError	(file, error) => void	—	Adapter rejected after auto-retries
onAllComplete	() => void	—	Queue drained

Returns

Property	Type	Description
files	UploadFile<TResponse>[]	Current list
addFiles	(files: File[]) => void	Validate and add
removeFile	(id: string) => void	Abort if needed and remove
upload	() => void	Start all pending files
retryFile	(id: string) => void	Retry error / cancelled
retryAll	() => void	Retry every retryable file
cancelFile	(id: string) => void	Abort in-flight; status cancelled
cancelAll	() => void	Abort all in-flight
clearCompleted	() => void	Drop success files
clearAll	() => void	Cancel everything and empty the list
isUploading	boolean	Any file has status uploading
totalProgress	number	Average progress 0–100
rejections	FileRejection[]	Last addFiles batch of rejects

Example

const uploader = useUploader<ApiResponse>({
  adapter,
  accept: ['image/*'],
  maxFileSize: 5 * 1024 * 1024,
  maxFiles: 10,
  autoUpload: true,
  concurrency: 2,
  maxRetries: 2,
  retryDelay: 1000,
  onUploadSuccess: (file, response) => {
    console.log(file.file.name, response.url);
  },
});

retryFile is a no-op unless status is error or cancelled. upload() only enqueues pending files.

See File lifecycle for status transitions and Adapters for the adapter contract.