File Upload React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

File Upload is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import FileUpload from @/components/ui/file-upload.

import { FileUpload, type UploadFile } from "@/components/ui/file-upload"

// your endpoint; signal aborts, onProgress fills the bar
function uploadFile(file: File, { signal, onProgress }: { signal: AbortSignal; onProgress: (fraction: number) => void }) {
  return new Promise<{ url: string }>((resolve, reject) => {
    const request = new XMLHttpRequest()
    request.open("POST", "/api/upload")
    request.upload.onprogress = (event) => onProgress(event.loaded / event.total)
    request.onload = () => (request.status < 300 ? resolve(JSON.parse(request.responseText)) : reject(new Error("Upload failed")))
    request.onerror = () => reject(new Error("No connection"))
    signal.addEventListener("abort", () => request.abort())
    const body = new FormData()
    body.append("file", file)
    request.send(body)
  })
}

const existing: UploadFile[] = [
  { id: "contract", name: "purchase-agreement.pdf", size: 1887437, type: "application/pdf", url: "/files/purchase-agreement.pdf", status: "done", progress: 1 },
]

export function PropertyDocuments() {
  return (
    <FileUpload
      label="Property documents"
      description="PDFs or images, up to 10 MB each"
      accept="image/*,.pdf"
      defaultValue={existing}
      upload={uploadFile}
      locale="en-US"
      labels={{ title: "Drop your documents here or", browse: "browse" }}
    />
  )
}

Props

• variantdefault "list"
  "list" | "grid" | "avatar" | "compact"

  list: a dropzone above a list of rows (documents). grid: photo tiles you can reorder, the first is the cover (listing photos). avatar: one round photo with a camera badge. compact: an attach button and small rows (chat, comments).

• acceptdefault ""
  string

  Accepted types, like the native attribute: "image/*,.pdf". Extensions match case-insensitively, wildcards match the MIME type. Also feeds the picker and the automatic hint. The exported acceptsFile(file, accept) runs the same check.

• maxSizedefault "10485760"
  number

  Largest file in bytes (10 MB); 0 means no limit. Bigger files are rejected with labels.tooLarge.

• maxFilesdefault 0
  number

  How many files the list may hold; 0 means no limit. Extra files are rejected, not dropped. At the limit the dropzone turns off and shows "8 / 8". The avatar always holds one.

• multipledefault true
  boolean

  Pick several files at once. Off, a new file replaces the current one.

• upload
  (file: File, context: { signal: AbortSignal; onProgress: (fraction: number) => void }) => Promise<unknown>

  Uploads one file. Pass signal to fetch so cancel, remove and unmount abort it, call onProgress with 0..1 (throttled to one update per 100ms per file). What it resolves with lands in the file's response; a rejection keeps the file with its error and a retry button. Without it files stay idle, for forms that submit them natively.

• autoUploaddefault true
  boolean

  Start uploads as files are added. Off, each row gets an upload button and the list an "Upload all" button.

• maxConcurrentdefault 3
  number

  Uploads that run at once; the rest wait their turn.

• sortabledefault true
  boolean

  Grid only: drag tiles to reorder (the first is the cover). A 250ms press on touch, Space and the arrow keys on a keyboard.

• cameradefault false
  boolean

  On touch screens, adds a "Take photo" button that opens the back camera (capture="environment", images).

• pastedefault true
  boolean

  Paste files and screenshots from the clipboard while focus is inside the component.

• validate
  (file: File) => (string | null | undefined)

  Extra checks after type and size: return a message to reject the file with it (a duplicate, a too-small photo). formatFileSize(bytes, locale) is exported for messages.

• onReject
  (rejections: { file: File; reason: "type" | "size" | "count" | "custom"; message: string }[]) => void

  Called with every rejected file of one add, together.

• sizedefault "md"
  "sm" | "md" | "lg"

  Dropzone padding and icon (list), the attach button (compact) and the avatar: 64 / 96 / 128px.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Corners of the dropzone and photo tiles: 0 / 12 / 16 / 24px (full stays 24px). The avatar is always round.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  Color of the drag-over tint, the progress bars and rings and the avatar badge.

• colordefault ""
  string

  Any CSS color; replaces the tone. Leave empty to use the tone.

• icon
  ReactNode

  The dropzone icon, CloudUpload by default.

• labels
  Partial<FileUploadLabels>

  Every string, English by default: title ("Drag files here or"), browse, tapTitle, dropHere, hint (else built from accept, maxSize and maxFiles), camera, add, attach, change, choose, cover, remove, retry, cancel, start, uploadAll, uploading, queued, uploaded, canceled, failed, limitReached, images / videos / audio, wrongType, tooLarge(max), tooMany(max), maxSizeHint(max, single), maxFilesHint(max), the announcements announceUploaded / announceFailed / announceRejected / announceRemoved and the reordering texts dragInstructions, dragStart, dragOver, dragEnd, dragCancel.

• localedefault ""
  string

  Formats file sizes ("2,4 MB" in ro-RO, "2.4 MB" in en-US). Empty uses the nearest LocaleProvider, then the page language.

• labeldefault ""
  ReactNode

  Renders the field anatomy around the component. A click on it focuses the dropzone without opening the picker.

• descriptiondefault ""
  ReactNode

  Helper text. In the list layout it becomes the dropzone's second line (unless labels.hint is set); elsewhere it shows under the component.

• errordefault ""
  ReactNode

  The animated error under the component; also marks the dropzone invalid.

• requireddefault false
  boolean

  The red * after the label; with name, the native form refuses to submit an empty list.

• invaliddefault false
  boolean

  The invalid look without a message.

• disableddefault false
  boolean

  Dims everything and blocks picking, dropping, pasting and the row actions.

• namedefault ""
  string

  Names the hidden file input. Its files follow the list (through DataTransfer), so a native form or FormData submits exactly the files shown.

• value
  UploadFile[]

  The files, controlled: { id, name, size, type, file?, url?, previewUrl?, status: "idle" | "uploading" | "done" | "error" | "canceled", progress, error?, response? }. Files that already exist on a server have url and status "done". Dropping a file mid-upload aborts it.

• defaultValuedefault "[]"
  UploadFile[]

  The starting files when uncontrolled; a form reset returns to them.

• onValueChange
  (files: UploadFile[]) => void

  The whole list after every add, remove, reorder, status change and throttled progress update.

• id
  string

  The main trigger's id (dropzone, add tile, avatar or attach button), which the label points to.

• fieldProps
  Partial<FieldProps>

  Anything else for the field wrapper: optional, labelAction, orientation, hideLabel.

• classNames
  Partial<Record<"dropzone" | "icon" | "title" | "hint" | "camera" | "rejections" | "list" | "item" | "thumb" | "name" | "meta" | "progress" | "action" | "grid" | "tile" | "cover" | "remove" | "add" | "avatar" | "input" | "field" | "label" | "description" | "error" | "counter", string>>

  Extra classes for the inner parts and the field parts.

• className
  string

  Extra classes for the root (the field root when a label, description or error is set).

Parts

FAQ

Used in

More React input components