Upload

A dropzone upload component with local validation, drag and drop, and a decoupled upload monitor hook

Installation

$npx litefy@latest add upload
$pnpm dlx litefy@latest add upload
$yarn dlx litefy@latest add upload
$bun --bun litefy@latest add upload

Usage

Upload only handles selection, drag-and-drop and local validation — it performs no network requests; pair it with the useUploadMonitor hook for actual uploads and progress.

Click to upload or drag and dropFiles are validated locally before acceptance

No files

"use client";

import * as React from "react";
import { List, Upload, useUploadMonitor, type UploadActions, type UploadReject } from "@/ui";

class MockXMLHttpRequest {
  status = 0;
  withCredentials = false;
  upload = { onprogress: null as ((event: ProgressEvent) => void) | null };
  onload: (() => void) | null = null;
  onerror: (() => void) | null = null;
  onabort: (() => void) | null = null;
  private timer: ReturnType<typeof setInterval> | null = null;
  private loaded = 0;
  private total = 4 * 1024 * 1024;

  open() {}
  setRequestHeader() {}
  send() {
    this.timer = setInterval(() => {
      this.loaded = Math.min(this.loaded + this.total / 25, this.total);
      this.upload.onprogress?.({
        lengthComputable: true,
        loaded: this.loaded,
        total: this.total,
      } as ProgressEvent);
      if (this.loaded >= this.total) this.finish();
    }, 120);
  }
  abort() {
    if (this.timer) {
      clearInterval(this.timer);
      this.timer = null;
      this.onabort?.();
    }
  }
  private finish() {
    if (this.timer) {
      clearInterval(this.timer);
      this.timer = null;
    }
    this.status = 200;
    this.onload?.();
  }
}

export default function UploadBasicDemo() {
  const actionsRef = React.useRef<UploadActions | null>(null);
  const [rejects, setRejects] = React.useState<UploadReject[]>([]);
  const upload = useUploadMonitor({ action: "mock://upload" });

  React.useEffect(() => {
    const Original = window.XMLHttpRequest;
    window.XMLHttpRequest = MockXMLHttpRequest as unknown as typeof XMLHttpRequest;
    return () => {
      window.XMLHttpRequest = Original;
    };
  }, []);

  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <Upload
        multiple
        maxCount={5}
        maxSize={2 * 1024 * 1024}
        actionsRef={actionsRef}
        onFilesAccepted={upload.acceptFiles}
        onFilesRejected={setRejects}
        onFileRemove={upload.removeItem}
      />

      {rejects.length > 0 && (
        <ul className="space-y-1 text-sm text-danger">
          {rejects.map((reject, index) => (
            <li key={index}>{reject.message}</li>
          ))}
        </ul>
      )}
      <List
        className="max-h-48"
        items={upload.fileList}
        getKey={(item) => item.uid}
        empty={
          <div className="px-3 py-4 text-center text-muted-foreground">No files</div>
        }
        renderItem={(item) => (
          <>
            <span className="flex-1 truncate">{item.file.name}</span>
            <span className="w-24 text-right text-muted-foreground">
              {item.status === "uploading" ? `${item.progress}%` : item.status}
            </span>
            <button
              type="button"
              className="text-danger hover:underline"
              onClick={() => actionsRef.current?.remove(item.uid)}
            >
              Remove
            </button>
          </>
        )}
      />
    </div>
  );
}

Disabled

When disabled, the dropzone ignores clicks, keyboard activation and drag-and-drop — queued items keep their state.

Click to upload or drag and dropFiles are validated locally before acceptance

"use client";

import { Upload } from "@/ui";

export default function UploadDisabledDemo() {
  return (
    <div className="w-full max-w-md">
      <Upload disabled />
    </div>
  );
}

Restrictions

accept, maxSize and maxCount are validated locally; rejected files are reported via onFilesRejected.

Click to upload or drag and dropFiles are validated locally before acceptance

Accepted: 0 · Rejected: 0 · Images and PDF up to 1 MB, max 4 files

"use client";import * as React from "react";import { Upload, type UploadItem, type UploadReject } from "@/ui";export default function UploadMultipleDemo() {  const [items, setItems] = React.useState<UploadItem[]>([]);  const [rejects, setRejects] = React.useState<UploadReject[]>([]);  return (    <div className="flex w-full max-w-md flex-col gap-3">      <Upload        multiple        accept="image/*,.pdf"        maxCount={4}        maxSize={1024 * 1024}        onFilesAccepted={(accepted) => setItems((prev) => [...prev, ...accepted])}        onFilesRejected={setRejects}      />      <p className="text-sm text-muted-foreground">        Accepted: {items.length} · Rejected: {rejects.length} · Images and PDF up to 1 MB, max 4        files      </p>    </div>  );}

Custom

Assemble the parts manually for full control over the dropzone content and behavior.

Custom dropzone content

"use client";

import * as React from "react";
import { UploadDropzone, UploadHiddenInput, UploadRoot } from "@/ui";

export default function UploadCustomDemo() {
  const inputRef = React.useRef<HTMLInputElement>(null);
  const [name, setName] = React.useState("");

  return (
    <UploadRoot className="w-full max-w-md">
      <UploadHiddenInput
        ref={inputRef}
        accept="image/*"
        aria-label="Upload image"
        onChange={(e) => setName(e.target.files?.[0]?.name ?? "")}
      />
      <UploadDropzone className="h-24" onClick={() => inputRef.current?.click()}>
        <span className="font-medium">{name || "Custom dropzone content"}</span>
      </UploadDropzone>
    </UploadRoot>
  );
}

Prop	Type	Default	Description
`accept`	`string`	-	Accepted file types (MIME types, `image/*` or extensions like `.pdf`)
`multiple`	`boolean`	`false`	Allow selecting multiple files
`maxCount`	`number`	-	Maximum number of simultaneously accepted items
`maxSize`	`number`	-	Maximum file size in bytes
`disabled`	`boolean`	`false`	Disables click, keyboard and drag interactions
`children`	`React.ReactNode`	-	Custom dropzone content; defaults to a hint text
`onFilesAccepted`	`(items: UploadItem[]) => void`	-	Called with validated items, each carrying `{ uid, file, signal }`
`onFilesRejected`	`(rejects: UploadReject[]) => void`	-	Called with rejected files and reasons (`accept` / `maxSize` / `maxCount`)
`onFileRemove`	`(uid: string) => void`	-	Called after `actionsRef.current.remove(uid)` aborts the item's controller
`onDragEnter`	`(e: React.DragEvent) => void`	-	Called when files are dragged into the dropzone
`onDragLeave`	`(e: React.DragEvent) => void`	-	Called when files are dragged out of the dropzone
`actionsRef`	`React.Ref<UploadActions>`	-	Imperative handle exposing `remove(uid)` and `clear()`; `remove` aborts the item's controller before firing `onFileRemove`
`className`	`ClassNameValue`	-	Custom class for the root
`style`	`React.CSSProperties`	-	Custom inline style for the root
`classNames`	`{ dropzone?; hiddenInput? }`	-	Custom classes for each part
`styles`	`{ dropzone?; hiddenInput? }`	-	Custom inline styles for each part

Installation

Usage

Disabled

Restrictions

Custom

API Reference

High-level Components

Upload

Composable Components

UploadRoot

UploadDropzone

UploadHiddenInput

On this page