File Upload

Playground

<FileUpload accept="image/*" multiple>
  <FileUploadDropzone>
    <ArrowUpToLineIcon className="size-6 stroke-1 text-muted-foreground" />
    <p className="pt-2 text-base font-medium text-foreground">
      Drop files here or click to upload
    </p>
    <FileUploadList>
      <FilesList />
    </FileUploadList>
  </FileUploadDropzone>
</FileUpload>

Preview

FileUploadDropzone accepts click, drop, paste and keyboard activation. Render accepted files inside FileUploadList by reading the store with useFileUpload and mapping to FileUploadItem.

<FileUpload multiple>
  <FileUploadDropzone>
    <ArrowUpToLineIcon className="size-6 stroke-1 text-muted-foreground" />
    <p className="pt-2 text-base font-medium text-foreground">
      Drop files here or click to upload
    </p>
    <p className="text-sm text-accent-foreground">
      Any file, multiple allowed
    </p>
    <FileUploadList>
      <FilesList /> {/* maps useFileUpload state to FileUploadItem */}
    </FileUploadList>
  </FileUploadDropzone>
</FileUpload>

Installation

npx shadcn@latest add https://espresso-base-ui.vercel.app/r/file-upload.json

Usage

import {
  FileUpload,
  FileUploadClear,
  FileUploadDropzone,
  FileUploadItem,
  FileUploadItemDelete,
  FileUploadItemMetadata,
  FileUploadItemPreview,
  FileUploadItemProgress,
  FileUploadList,
  FileUploadTrigger,
  useFileUpload,
} from "@/components/ui/file-upload"

function Files() {
  const fileStates = useFileUpload((state) => Array.from(state.files.values()))
  return (
    <>
      {fileStates.map((fs) => (
        <FileUploadItem key={fs.file.name} value={fs.file}>
          <FileUploadItemPreview />
          <FileUploadItemMetadata />
          <FileUploadItemDelete asChild>
            <Button variant="ghost" size="icon-sm">
              <Trash />
            </Button>
          </FileUploadItemDelete>
        </FileUploadItem>
      ))}
    </>
  )
}

<FileUpload multiple onValueChange={setFiles}>
  <FileUploadDropzone>
    <p>Drop files here</p>
    <FileUploadList>
      <Files />
    </FileUploadList>
  </FileUploadDropzone>
</FileUpload>

Trigger button

Skip the dropzone entirely: FileUploadTrigger opens the file picker from any button, and FileUploadClear removes every file (it only renders while files are present).

<FileUpload multiple maxFiles={5}>
  <div className="flex items-center gap-2">
    <FileUploadTrigger asChild>
      <Button variant="outline" size="sm">
        <UploadIcon />
        Browse files
      </Button>
    </FileUploadTrigger>
    <FileUploadClear asChild>
      <Button variant="ghost" size="sm">
        Clear all
      </Button>
    </FileUploadClear>
  </div>
  <FileUploadList>
    <FilesList />
  </FileUploadList>
</FileUpload>

Validation

accept, maxFiles and maxSize reject non-conforming files, briefly flagging the dropzone invalid; handle rejections in onFileReject (or run custom checks in onFileValidate).

<FileUpload
  accept="image/*"
  maxFiles={3}
  maxSize={2 * 1024 * 1024}
  multiple
  onFileReject={(file, message) => toast.error(file.name + ": " + message)}
>
  <FileUploadDropzone>
    <ArrowUpToLineIcon className="size-6 stroke-1 text-muted-foreground" />
    <p className="pt-2 text-base font-medium text-foreground">
      Drop images here
    </p>
    <p className="text-sm text-accent-foreground">
      PNG / JPG / GIF – up to 2 MB each, max 3 files
    </p>
    <FileUploadList>
      <FilesList />
    </FileUploadList>
  </FileUploadDropzone>
</FileUpload>

Upload progress

Pass onUpload to start uploading as soon as files are accepted – report per-file progress through the provided callbacks and FileUploadItemProgress renders it as a linear bar, a circular ring or a fill overlay.

<FileUpload
  multiple
  onUpload={async (files, { onProgress, onSuccess, onError }) => {
    await Promise.all(
      files.map((file) => uploadToServer(file, onProgress, onSuccess))
    )
  }}
>
  <FileUploadDropzone>
    <ArrowUpToLineIcon className="size-6 stroke-1 text-muted-foreground" />
    <p className="pt-2 text-base font-medium text-foreground">
      Drop files to upload
    </p>
    <FileUploadList>
      {/* items render <FileUploadItemProgress variant="linear" /> */}
      <FilesList progress="linear" />
    </FileUploadList>
  </FileUploadDropzone>
</FileUpload>

API reference

FileUpload is fully composable: the root owns the file store and a visually hidden input type="file", and every part supports asChild to merge onto your own element. Files work controlled (value + onValueChange) or uncontrolled (defaultValue).

Accessibility & styling hooks

The real input type="file" stays in the tree (visually hidden) so forms and assistive tech see a native control, labelled via aria-labelledby from the label prop. The dropzone is a focusable role="region" that opens the picker on Enter or Space and reflects aria-invalid and aria-disabled; items announce name, size and upload status through aria-describedby and progress uses a proper role="progressbar".

For styling, every part carries a data-slot attribute, and the dropzone additionally exposes data-dragging while a drag hovers it, plus data-invalid and data-disabled – target these from CSS for custom drop states.