Hooks

The library exposes two hooks. useUpload gives you the full upload context: file list, actions, and derived state, and is the primary way to drive your UI. useFile subscribes to a single file by id, returning just that file’s state without re-rendering on unrelated changes elsewhere in the queue.

useUpload

The primary hook for reading upload state and triggering actions. Must be called within an UploadProvider.

const {
  files,              // FileState[]
  addFiles,           // (files: FileRef[]) => void
  removeFile,         // (id: string) => void
  retryFile,          // (id: string) => void
  updateFileStatus,   // (videoId, status, data?) => void
  canAddMore,         // boolean: false when files.length >= maxFiles
  maxFiles,           // number | undefined
  isUploading,        // true if any file is validating or uploading
  hasErrors,          // true if any file is failed
  allReady,           // true when all files are ready (and list non-empty)
  allSettled,         // true when all files are ready or failed (and list non-empty)
  readyCount,         // number of files with status "ready"
  failedCount,        // number of files with status "failed"
} = useUpload();

updateFileStatus

Manually transition a processing file to ready or failed, or patch playback/thumbnail data on an already-ready file. Use this when you drive status updates via a webhook, SSE, or realtime broadcast instead of polling.

const { updateFileStatus } = useUpload();

// Flip ready immediately on broadcast; fetch URL separately.
updateFileStatus(videoId, "ready");

// Patch the URL when your fetch resolves.
updateFileStatus(videoId, "ready", { playbackUrl });

// Or provide both at once.
updateFileStatus(videoId, "ready", { playbackUrl, thumbnailUri });

// Mark failed.
updateFileStatus(videoId, "failed");

A processing → ready | failed call transitions status. A repeat (videoId, "ready", data) call on an already-ready file patches data in without changing status. Calls for unknown video IDs, or "failed" on an already-ready file, are no-ops.

useFile

Subscribes to a single file in the upload queue by id. Returns the matching FileState, or undefined if no file with that id exists (for example, after removeFile runs).

function useFile(fileId: string): FileState | undefined;

Useful when a component holds a file id (from a route param, persisted state, or a parent that only forwards an id) and wants to render that file’s live state without threading the full file object as a prop.

import { useFile } from "@hyperserve/video-uploader";

function FileStatusLine({ fileId }: { fileId: string }) {
  const file = useFile(fileId);
  if (!file) return null;
  return <div>{file.ref.name}: {file.status}</div>;
}