React file uploads with Uppy: resumability, previews, validation, and processing

Define what “complete” means before writing the component

A browser can finish sending bytes while the resulting media is still being inspected, transformed, and exported. Decide which state the interface calls complete: file selection, transfer, Assembly creation, processing, durable storage, or publication in the application. The three tiers below group file selection and transfer under transfer success, Assembly creation and processing under processing success, and durable storage and publication under application success. A React component may display several of these states, but it should not collapse them into one success flag.

For a Transloadit workflow, Uppy owns the browser-side queue and transfer state. The Transloadit plugin creates an Assembly and associates each local file with that workflow. Your application should retain the Assembly ID as soon as it exists, then reconcile the terminal result outside the component when processing can outlive the page. A completed progress bar is not a durable asset record.

Create one configured Uppy instance per mounted uploader

Install Core, Dashboard, the React interface package, the maintained Transloadit plugin, and the Zod schema validator for the authorization response. Import each Uppy stylesheet once from a stable entry point so its load order stays predictable. The component example below imports the package styles directly; move those imports to the application entry point if that is where your framework or bundler owns global styles.

Construct Uppy once for the lifetime of the mounted form. A lazy useState initializer in the next section gives each mounted uploader its own instance without rebuilding it on rerenders. Do not create a shared module-level singleton unless every surface is intentionally one queue: independent forms would otherwise see and remove one another’s files.

The asynchronous assemblyOptions function asks a trusted endpoint for authorization immediately before upload. The endpoint must authenticate and authorize the current user, apply abuse controls, choose a constrained Template, and return a short-lived signed payload. The browser validates the response shape but never receives the Auth Secret.

yarn add @uppy/core @uppy/dashboard @uppy/react @uppy/transloadit zod

import Uppy from '@uppy/core'
import Transloadit from '@uppy/transloadit'
import { z } from 'zod'

const assemblyOptionsSchema = z.object({
  params: z.string().min(1),
  signature: z.string().regex(/^(sha1|sha256|sha384):[0-9a-f]+$/),
})

async function fetchAssemblyOptions(): Promise<z.infer<typeof assemblyOptionsSchema>> {
  const response = await fetch('/api/transloadit-params', {
    method: 'POST',
    headers: { Accept: 'application/json' },
  })

  if (!response.ok) {
    throw new Error('Could not authorize this upload')
  }

  const responseBody: unknown = await response.json().catch(() => null)
  const parsedOptions = assemblyOptionsSchema.safeParse(responseBody)
  if (!parsedOptions.success) {
    throw new Error('Could not authorize this upload')
  }

  return parsedOptions.data
}

export function createImageUploader(): Uppy {
  return new Uppy({
    autoProceed: false,
    restrictions: {
      allowedFileTypes: ['image/jpeg', 'image/png', 'image/webp'],
      maxFileSize: 50 * 1024 * 1024,
      maxNumberOfFiles: 5,
    },
  }).use(Transloadit, {
    assemblyOptions: fetchAssemblyOptions,
    retryDelays: [0, 1_000, 3_000, 5_000],
    waitForEncoding: false,
  })
}

Render progress, cancellation, and Assembly state from Uppy

Uppy is an external state store. useUppyState subscribes React to selected values without maintaining a second queue in component state, while useUppyEvent exposes events that are not durable store fields. The component reads file count, aggregate progress, active upload state, the raw error state, and the Assembly-created event. It maps the error to a stable user-facing message instead of displaying the raw value, and it does not mirror individual files into a separate useState value.

Dashboard provides file selection, drag-and-drop, previews for supported local files, per-file status, and upload controls. The separate live region gives the surrounding application a concise status announcement, and the native disabled button exposes whether cancellation is available. Keep the Dashboard’s own labels localized when the product supports multiple languages; the surrounding heading, status, and errors need the same treatment.

Destroy the Uppy instance when its owning component unmounts. Destruction cancels current work, removes installed plugins, and releases listeners. A route change therefore should not be the only copy of important progress: retain the Assembly ID and any application task record before depending on work that may continue elsewhere.

import type { ReactNode } from 'react'

import Dashboard from '@uppy/react/dashboard'
import { useUppyEvent, useUppyState } from '@uppy/react'
import { useEffect, useState } from 'react'

import { createImageUploader } from './createImageUploader.ts'

import '@uppy/core/css/style.min.css'
import '@uppy/dashboard/css/style.min.css'

export function ReactFileUploader(): ReactNode {
  const [uppy] = useState(createImageUploader)
  const error = useUppyState(uppy, (state) => state.error)
  const fileCount = useUppyState(uppy, (state) => Object.keys(state.files).length)
  const isUploading = useUppyState(
    uppy,
    (state) => Object.keys(state.currentUploads).length > 0,
  )
  const progress = useUppyState(uppy, (state) => state.totalProgress)
  const [assemblyCreatedArgs, clearAssemblyCreated] = useUppyEvent(
    uppy,
    'transloadit:assembly-created',
  )
  useUppyEvent(uppy, 'cancel-all', clearAssemblyCreated)
  const [assembly] = assemblyCreatedArgs
  const assemblyId = assembly?.assembly_id

  useEffect(() => {
    return () => uppy.destroy()
  }, [uppy])

  let status = 'Choose up to five JPEG, PNG, or WebP images.'
  if (fileCount > 0) status = 'Ready to upload.'
  if (isUploading) status = `Upload ${progress}% complete.`
  if (!isUploading && progress === 100) status = 'Files transferred. Processing may continue.'
  if (error != null) status = 'Upload failed. Check the selected files and try again.'

  return (
    <section aria-labelledby="file-upload-heading">
      <h2 id="file-upload-heading">Upload images</h2>
      <Dashboard height={420} uppy={uppy} />
      <p aria-live="polite" role="status">
        {status}
      </p>
      {assemblyId != null ? (
        <p>
          Processing reference: <code>{assemblyId}</code>
        </p>
      ) : null}
      <button disabled={fileCount === 0} onClick={() => uppy.cancelAll()} type="button">
        Cancel and remove files
      </button>
    </section>
  )
}

Use previews and restrictions as interface features, not trust boundaries

A local preview helps a person catch the wrong selection before paying the upload cost. It is not the processed output and does not prove that the file is safe, decodable, correctly oriented, or honestly labeled. Keep preview work bounded because decoding many large images consumes browser memory. For formats the browser cannot preview, show the filename, declared type, and size without inventing a thumbnail.

Uppy restrictions reject obvious mistakes early: allowed types, individual size, aggregate size, and file count. Repeat the same limits at a trusted receiver or in the saved Template because a caller can bypass React and modify file metadata. Use detected content and a processing attempt where appropriate, then store only accepted results. Keep allow_steps_override disabled when the browser must not replace the approved workflow. When a preview or restriction rejects a selection, show a stable user-facing message and keep raw provider responses, stack traces, credentials, and storage diagnostics out of the page.

Design resumability around the interruption you need to survive

The Transloadit plugin uploads local files through tus, which can continue a failed transfer from a server-confirmed offset while the upload resource remains valid. retryDelays handles a bounded set of transient failures during the current Uppy lifetime. Cancellation is different: cancelAll() intentionally aborts current work, removes the files, and resets upload state, so the interface should say that the selection will be removed.

A page reload destroys in-memory React and Uppy state. Reload recovery requires persisted client state and compatible server upload resources, such as a deliberately configured Golden Retriever plugin workflow. Test that behavior with the actual Transloadit integration before promising it. Persisted local metadata can become stale, sensitive, or inconsistent with expired authorization, so define retention and a way to discard unrecoverable entries.

Resumability also has an operational deadline. An Assembly cannot remain uploadable forever, and short-lived signed parameters can expire before a delayed retry starts. Distinguish automatic retry, pause and resume, reload restoration, and starting a new Assembly; they solve different failures and may reuse different identifiers.

Hand transferred files to an asynchronous media workflow

A saved Template should describe the allowed processing graph: /upload/handle receives the browser files, /file/filter can reject unsupported observed inputs, transformation Robots produce bounded derivatives, and storage Robots export approved results when durable storage is part of the workflow. The signed request selects that Template; React does not construct arbitrary Steps or carry permanent storage credentials.

Choose waitForEncoding from the interface contract. Setting it to false lets the browser finish after transfer and is appropriate when the application records the Assembly ID, shows a separate processing state, and learns the terminal result from a verified Assembly Notification or a later Assembly Status lookup. Waiting for encoding can keep the interface aligned with short processing, but it does not replace durable reconciliation if the tab closes.

Store application-level context next to the Assembly ID: authenticated user or tenant, intended asset slot, Template ID, creation time, and the application operation that caused it. When a notification arrives, verify its signature, handle duplicate delivery idempotently, confirm that the Assembly belongs to the expected record, and save only the result fields the product needs.

Test lifecycle and failure behavior, not only the happy path

Exercise the component with a permitted small file, an oversized file, a misleading extension, an unsupported type, several files at the count boundary, a zero-byte input, a slow connection, an offline interval, server rejection, authorization expiry, user cancellation, component unmount, and a page reload. Confirm which state is retained, which work is aborted, and which message a keyboard or screen-reader user receives.

Test the real signing and processing path in addition to isolated React behavior. A mock can prove that the button disables or a status changes, but only an integrated fixture proves that the signed parameters match, tus resumes from the expected offset, the Template rejects bad content, the Assembly ID is recorded, and completion is reconciled once. Keep fixture files small and remove temporary production data after the run.