Upload

Overview

Upload renders the dropzone — a click-to-browse box that also accepts drag-and-drop — and automatically renders the resulting file list as UploadItem rows underneath it. It works two ways:

• Uncontrolled (default) — just drop <Upload /> in and it manages its own file list. Pass uploadFn to actually perform the upload and get real progress/complete/error rows for free; omit it and every accepted file is simply marked complete, since this design system has no upload transport of its own.
• Controlled — pass files yourself (an array of UploadFileEntry) and Upload still renders the rows, but never mutates the array; use onRemoveFile to react to the remove button and update your own state.

Either way, UploadItem (the row) stays fully presentational and can also be used completely standalone.

Import

import { Upload } from '@unflow.io/ui/components/Upload';
import { UploadItem } from '@unflow.io/ui/components/UploadItem';

Upload props

interface UploadFileEntry {
  id: string;
  file: File;
  status: 'uploading' | 'complete' | 'error';
  progress?: number;
  error?: ReactNode;
}

UploadItem props

Basic usage

<Upload />

Uncontrolled — batteries included

Pass uploadFn and Upload does the rest: picked/dropped files show up as rows immediately, each one's progress ring is driven by your onProgress calls, and removing a row aborts its signal. No state to wire up yourself.

function uploadToServer(file: File, { onProgress, signal }: {
  onProgress: (percent: number) => void;
  signal: AbortSignal;
}) {
  return fetch('/api/upload', { method: 'POST', body: file, signal }).then(() => {
    onProgress(100);
  });
}

<Upload maxSize={5 * 1024 * 1024} uploadFn={uploadToServer} />

Controlled — you own the list

Pass files instead, and Upload still renders the rows for you — it just never mutates the array. Use onFilesAdded to append and onRemoveFile to remove, exactly like any other controlled input.

Disabled

<Upload disabled />

Full-screen drop target

Set presentation="fullScreen" to listen for file drags anywhere on the page instead of just the component's own box. No persistent box is rendered — dragging a file over the window reveals the dropzone centered in a full-viewport overlay (built on top of the existing Backdrop component, and centered the same way Modal's center placement is), and it disappears again on drop, drag-cancel, or Escape. Since there's no click target to reach in this mode, the divider and "Select files" button are omitted — only the icon, title, and hint show. The row list still renders normally wherever Upload sits in your layout, and persists after the overlay closes.

<Upload presentation="fullScreen" uploadFn={uploadToServer} />

Inside a Popper, with search

Upload is just a regular block-level component, so it composes directly with Dropdown (built on Popper) for a dropdown-style upload panel — reusing the same header pattern SelectDropdown uses for search: the field itself stays hidden behind an IconButton (a magnifying glass) and only appears once toggled, rather than sitting open by default. Wire the Input's value straight into Upload's searchQuery prop to filter the visible rows by file name without touching the underlying list.

File row states

<UploadItem
  fileName="file_example.pdf"
  fileSize={1_048_576}
  fileType="application/pdf"
  status="uploading"
  progress={45}
/>
<UploadItem fileName="video_example.mov" fileSize={3_145_728} fileType="video/quicktime" />
<UploadItem
  fileName="image_example.jpg"
  fileType="image/jpeg"
  status="error"
  error="The file exceeds the 5 MB size limit."
/>

Indeterminate progress

When a file is uploading but no progress value is available to measure, omit the prop entirely — UploadItem falls back to an indeterminate spinner instead of a progress ring.

Custom icons per file

UploadItem used on its own already accepts slots.icon to override its icon outright. When Upload is rendering the built-in row list for you, use slots.fileIcon instead — it's called once per row with that row's UploadFileEntry, so you can key off the file's name, type, or anything else you know about it and swap in a custom icon (or an image thumbnail) for just that file, while every other row keeps the automatic file/image/video/audio icon.

<Upload
  slots={{
    fileIcon: (entry) =>
      entry.file.type.startsWith('image/') ? (
        <img src={URL.createObjectURL(entry.file)} className="h-4 w-4 rounded object-cover" />
      ) : undefined, // fall back to the default icon for everything else
  }}
/>

Customization (slots & slotProps)

Upload

UploadItem

Accessibility

• Upload's drag-and-drop is a progressive enhancement layered on top of a real Button, which stays keyboard-operable and screen-reader visible on its own — the surrounding clickable box is a mouse-only convenience, not a duplicate interactive control.
• Because browsers never expose a dragged file's name until it's dropped, the chips shown while dragging over the dropzone use generic type labels ("File", "Image", "Video", "Audio") derived from the drag payload's MIME type, rather than real file names.
• UploadItem's indeterminate state renders a role="status" spinner; its determinate state renders Progress's role="progressbar" with aria-valuenow — assistive tech gets an accurate reading either way.
• The "Error" label is wrapped in a Tooltip, so the underlying error message is reachable by keyboard focus, not just mouse hover.
• Removing a row while its uploadFn is still in flight aborts the associated AbortSignal — pass it through to fetch/your HTTP client so the underlying request is actually cancelled, not just hidden.