Skip to content

Design system

Documentation

DesignPatterns / Upload Flow

Patterns / Upload Flow

Beta

Upload flow

An upload flow keeps the file queue controlled by the feature and reports validation, progress, failure, and recovery for each file.

On this page

Examples

Controlled queue and retry

Manage each file status in the feature and show progress, error, and retry feedback without a service request.

Upload attachments

Feature state owns the controlled queue. These controls simulate progress and retry without a backend request.

Attachments

PDF, PNG, and JPEG files up to 5 MB each; the queue is controlled by this feature.

No files in the queue.

Controlled file upload queue with progress and retry states

Controlled queue

The feature owns the ordered file list and supplies it to FileUpload. The component validates local accept and size rules, then emits proposed queue changes. The feature owns upload requests, status transitions, retry policy, cancellation, and persistence; this example uses fixture-only state.

States and retry

  • queued: keep the file name and size visible before upload begins.
  • uploading: show per-file Progress and prevent duplicate work in the feature.
  • success: report completion without leaving stale retry controls visible.
  • error: explain the failed file and preserve its context; offer Retry only when the feature can safely resume.

Accessibility

  • Name the queue and each remove/retry action with the affected file.
  • Expose validation failures and transfer failures in text, not only with a color or progress change.
  • Keep the file list in a bounded scroll region when it can grow; preserve the queue heading and controls.
  • Announce state changes near the queue and do not move focus when a progress value updates.

Do and don’t

Do

Keep files and statuses in feature state so retries and completion remain controlled and testable.

Don’t

Assume that selecting a file uploads it, or put service-specific network behavior inside FileUpload.

The runnable source at src/components/design/examples/source/upload-flow-pattern.tsx simulates each transition locally and makes no request. The composition has no pattern-level property playground.

  • FileUpload owns the picker, queue presentation, and validation surface.
  • Progress describes an active transfer.
  • Alert presents actionable failures.