"use client"; /** * @author: @dorianbaffier * @description: File Upload * @version: 2.0.0 * @date: 2026-10-16 * @license: MIT * @website: https://kokonutui.com * @github: https://github.com/kokonut-labs/kokonutui */ import { RotateCw, Upload, X } from "lucide-react"; import { AnimatePresence, motion, useReducedMotion } from "motion/react"; import { type ChangeEvent, type ClipboardEvent, type DragEvent, useCallback, useEffect, useId, useRef, useState, } from "react"; import { cn } from "@/lib/utils"; export interface FileError { message: string; code: string; } export interface UploadHelpers { /** Report upload progress from 0 to 100. */ onProgress: (percent: number) => void; /** Aborted when the row is removed or the component unmounts. */ signal: AbortSignal; } export interface FileUploadProps { /** * Uploads one file. Called once per file, a few at a time. Resolve to mark * the row done, reject to show the error with a Retry button. When omitted, * uploads are simulated over `uploadDelay`. */ onUpload?: (file: File, helpers: UploadHelpers) => Promise; onUploadSuccess?: (file: File) => void; /** Called for validation errors and failed uploads. */ onUploadError?: (error: FileError, file: File) => void; /** Called with every uploaded file once nothing is queued or in flight. */ onComplete?: (files: File[]) => void; /** Called when a row is removed (cancelling its upload if needed). */ onFileRemove?: (file: File) => void; /** MIME types ("image/png"), wildcards ("image/*") or extensions (".pdf"). */ acceptedFileTypes?: string[]; /** Maximum size of each file in bytes. Defaults to 5 MB. */ maxFileSize?: number; /** Accept several files at once. Defaults to true. */ multiple?: boolean; /** Maximum number of files in the list. Defaults to 5. */ maxFiles?: number; /** Simulated upload duration per file in ms, used without `onUpload`. */ uploadDelay?: number; /** Simulated uploads only: the first attempt of every third file fails. */ simulateFailure?: boolean; validateFile?: (file: File) => FileError | null; className?: string; } type ItemStatus = "queued" | "uploading" | "done" | "error" | "rejected"; interface QueueItem { id: string; file: File; index: number; status: ItemStatus; progress: number; attempts: number; error?: FileError; previewUrl?: string; } const DEFAULT_MAX_FILE_SIZE = 5 * 1024 * 1024; const CONCURRENCY = 3; const SIMULATED_TICK = 80; const EASE_OUT = [0.23, 1, 0.32, 1] as const; const FILE_SIZES = ["B", "KB", "MB", "GB", "TB"] as const; // Module constant, so the default does not change identity every render. const NO_ACCEPTED_TYPES: string[] = []; const formatBytes = (bytes: number): string => { if (!bytes) { return "0 B"; } const i = Math.min( Math.floor(Math.log(bytes) / Math.log(1024)), FILE_SIZES.length - 1 ); const value = bytes / 1024 ** i; return `${value >= 10 || i === 0 ? Math.round(value) : Number(value.toFixed(1))} ${FILE_SIZES[i]}`; }; // Accepts exact MIME types ("image/png"), wildcards ("image/*") and // extensions (".pdf"), like the input's `accept` attribute. const matchesAcceptedType = (file: File, acceptedType: string): boolean => { const accepted = acceptedType.trim().toLowerCase(); if (!accepted) { return false; } if (accepted.startsWith(".")) { return file.name.toLowerCase().endsWith(accepted); } const fileType = file.type.toLowerCase(); if (accepted.endsWith("/*")) { return fileType.startsWith(accepted.slice(0, -1)); } return fileType === accepted; }; // ".pdf" -> "PDF", "image/svg+xml" -> "SVG", "image/*" -> "images". const describeAcceptedType = (acceptedType: string): string => { const accepted = acceptedType.trim(); if (accepted.startsWith(".")) { return accepted.slice(1).toUpperCase(); } const [kind = "", subtype = ""] = accepted.split("/"); if (subtype === "*") { return `${kind.toLowerCase()}s`; } return subtype.split("+")[0].toUpperCase(); }; const describeAcceptedTypes = (acceptedTypes: string[]): string => { const labels = acceptedTypes.map(describeAcceptedType).filter(Boolean); if (!labels.length) { return "Any file"; } const text = labels.length > 1 ? `${labels.slice(0, -1).join(", ")} or ${labels.at(-1)}` : labels[0]; return text.charAt(0).toUpperCase() + text.slice(1); }; const extensionOf = (name: string): string => { const dot = name.lastIndexOf("."); if (dot <= 0 || dot === name.length - 1) { return "FILE"; } return name .slice(dot + 1) .slice(0, 4) .toUpperCase(); }; const clampProgress = (value: number) => Math.min(Math.max(value, 0), 100); const isFileDrag = (e: { dataTransfer: DataTransfer | null }) => Boolean(e.dataTransfer?.types.includes("Files")); const countDraggedFiles = (dataTransfer: DataTransfer): number => { let count = 0; for (const item of dataTransfer.items) { if (item.kind === "file") { count += 1; } } return count; }; // Default upload: advances in uneven steps, like a real network would. const simulateUpload = ( { onProgress, signal }: UploadHelpers, duration: number, shouldFail: boolean ): Promise => new Promise((resolve, reject) => { if (duration <= 0) { resolve(); return; } let progress = 0; const interval = setInterval(() => { progress = Math.min( progress + (100 * SIMULATED_TICK * (0.4 + Math.random() * 1.2)) / duration, 100 ); if (shouldFail && progress >= 58) { clearInterval(interval); reject(new Error("Connection lost")); return; } onProgress(progress); if (progress >= 100) { clearInterval(interval); resolve(); } }, SIMULATED_TICK); signal.addEventListener("abort", () => { clearInterval(interval); reject(new DOMException("Upload cancelled", "AbortError")); }); }); const buildItems = ( files: File[], { room, validate, nextId, }: { room: number; validate: (file: File) => FileError | null; nextId: () => { id: string; index: number }; } ) => { const added: QueueItem[] = []; let accepted = 0; let skipped = 0; for (const file of files) { const error = validate(file) ?? undefined; if (!error && accepted >= room) { skipped += 1; continue; } if (!error) { accepted += 1; } const { id, index } = nextId(); added.push({ id, file, index, status: error ? "rejected" : "queued", progress: 0, attempts: 0, error, previewUrl: !error && file.type.startsWith("image/") ? URL.createObjectURL(file) : undefined, }); } return { added, skipped }; }; const summarize = (items: QueueItem[]) => { let done = 0; let failed = 0; let busy = false; for (const item of items) { if (item.status === "done") { done += 1; } else if (item.status === "error" || item.status === "rejected") { failed += 1; } else { busy = true; } } return { done, failed, busy }; }; const zoneCopy = ({ isFull, overZone, windowDrag, multiple, limit, maxFileSize, acceptedFileTypes, }: { isFull: boolean; overZone: number; windowDrag: boolean; multiple: boolean; limit: number; maxFileSize: number; acceptedFileTypes: string[]; }) => { const noun = multiple ? "files" : "a file"; if (isFull) { return { title: "File limit reached", showBrowse: false, hint: "Remove a file to add another", }; } const sizeHint = maxFileSize > 0 && Number.isFinite(maxFileSize) ? ` up to ${formatBytes(maxFileSize)}` : ""; const hint = `${describeAcceptedTypes(acceptedFileTypes)}${sizeHint}${multiple ? ` · ${limit} max` : ""}`; if (overZone) { return { title: `Release to add ${overZone} ${overZone === 1 ? "file" : "files"}`, showBrowse: false, hint, }; } if (windowDrag) { return { title: `Drop ${noun} here`, showBrowse: false, hint }; } return { title: `Drop ${noun} here or `, showBrowse: true, hint }; }; const FileThumb = ({ item }: { item: QueueItem }) => { if (item.previewUrl) { return ( ); } return ( ); }; const DoneCheck = ({ reduceMotion }: { reduceMotion: boolean | null }) => ( ); const statusLine = (item: QueueItem): string => { switch (item.status) { case "queued": return "Waiting"; case "uploading": return `${Math.round(item.progress)}%`; case "done": return "Uploaded"; case "error": case "rejected": return item.error?.message ?? "Upload failed"; default: return ""; } }; const iconButton = "flex size-7 shrink-0 items-center justify-center rounded-md text-zinc-400 outline-none transition-colors duration-150 hover:bg-zinc-100 hover:text-zinc-900 focus-visible:ring-2 focus-visible:ring-zinc-900/20 active:bg-zinc-200 dark:text-zinc-500 dark:active:bg-zinc-700 dark:focus-visible:ring-white/25 dark:hover:bg-zinc-800 dark:hover:text-zinc-100"; const QueueRow = ({ item, reduceMotion, onRemove, onRetry, }: { item: QueueItem; reduceMotion: boolean | null; onRemove: (id: string) => void; onRetry: (id: string) => void; }) => { const failed = item.status === "error" || item.status === "rejected"; const inFlight = item.status === "uploading" || item.status === "queued"; const name = item.file.name; return (

{name}

{formatBytes(item.file.size)} {statusLine(item)}

{item.status === "done" && ( )} {item.status === "error" && ( )}

{/* The row's hairline divider doubles as its progress bar. */}

); }; export default function FileUpload({ onUpload, onUploadSuccess, onUploadError, onComplete, onFileRemove, acceptedFileTypes = NO_ACCEPTED_TYPES, maxFileSize = DEFAULT_MAX_FILE_SIZE, multiple = true, maxFiles = 5, uploadDelay = 2000, simulateFailure = false, validateFile, className, }: FileUploadProps) { const [items, setItems] = useState([]); const [notice, setNotice] = useState(null); const [windowDrag, setWindowDrag] = useState(false); const [overZone, setOverZone] = useState(0); const reduceMotion = useReducedMotion(); const baseId = useId(); const hintId = `${baseId}-hint`; const inputRef = useRef(null); const nextIndex = useRef(0); const controllers = useRef(new Map()); const previewUrls = useRef(new Map()); const wasBusy = useRef(false); // Latest callbacks, read from async upload code without re-running effects. const latest = useRef({ onUpload, onUploadSuccess, onUploadError, onComplete, uploadDelay, simulateFailure, }); useEffect(() => { latest.current = { onUpload, onUploadSuccess, onUploadError, onComplete, uploadDelay, simulateFailure, }; }); const limit = multiple ? Math.max(1, maxFiles) : 1; const counted = items.filter((item) => item.status !== "rejected").length; const isFull = counted >= limit; const updateItem = useCallback( (id: string, patch: Partial) => setItems((prev) => prev.map((item) => (item.id === id ? { ...item, ...patch } : item)) ), [] ); const runUpload = useCallback( (item: QueueItem) => { const controller = new AbortController(); controllers.current.set(item.id, controller); const { signal } = controller; const cb = latest.current; const onProgress = (percent: number) => { if (!signal.aborted) { updateItem(item.id, { progress: clampProgress(percent) }); } }; const succeed = () => { if (signal.aborted) { return; } controllers.current.delete(item.id); updateItem(item.id, { status: "done", progress: 100 }); latest.current.onUploadSuccess?.(item.file); }; const fail = (reason: unknown) => { if (signal.aborted) { return; } controllers.current.delete(item.id); const error = { message: reason instanceof Error && reason.message ? reason.message : "Upload failed", code: "UPLOAD_FAILED", }; updateItem(item.id, { status: "error", error }); latest.current.onUploadError?.(error, item.file); }; if (cb.onUpload) { const upload = cb.onUpload; Promise.resolve() .then(() => upload(item.file, { onProgress, signal })) .then(succeed, fail); return; } const shouldFail = cb.simulateFailure && item.attempts === 1 && item.index % 3 === 1; simulateUpload({ onProgress, signal }, cb.uploadDelay, shouldFail).then( succeed, fail ); }, [updateItem] ); // Scheduler: keep up to CONCURRENCY uploads in flight. useEffect(() => { const active = items.filter((item) => item.status === "uploading").length; const toStart = items .filter((item) => item.status === "queued") .slice(0, Math.max(0, CONCURRENCY - active)) .filter((item) => !controllers.current.has(item.id)) .map((item) => ({ ...item, attempts: item.attempts + 1 })); if (!toStart.length) { return; } const started = new Map(toStart.map((item) => [item.id, item])); setItems((prev) => prev.map((item) => { const next = started.get(item.id); return next ? { ...next, status: "uploading", progress: 0 } : item; }) ); for (const item of toStart) { runUpload(item); } }, [items, runUpload]); // Settle: report once nothing is queued or in flight. useEffect(() => { const busy = items.some( (item) => item.status === "queued" || item.status === "uploading" ); if (wasBusy.current && !busy) { latest.current.onComplete?.( items.filter((item) => item.status === "done").map((item) => item.file) ); } wasBusy.current = busy; }, [items]); // Abort uploads and free previews on unmount. useEffect(() => { const ctrl = controllers.current; const urls = previewUrls.current; return () => { for (const controller of ctrl.values()) { controller.abort(); } ctrl.clear(); for (const url of urls.values()) { URL.revokeObjectURL(url); } urls.clear(); }; }, []); // A file dragged anywhere over the window wakes the drop zone, and a drop // that misses it does not make the browser navigate away to the file. useEffect(() => { let depth = 0; const onEnter = (e: globalThis.DragEvent) => { if (!isFileDrag(e)) { return; } depth += 1; setWindowDrag(true); }; const onLeave = (e: globalThis.DragEvent) => { if (!isFileDrag(e)) { return; } depth = Math.max(0, depth - 1); if (depth === 0) { setWindowDrag(false); } }; const onOver = (e: globalThis.DragEvent) => { if (isFileDrag(e)) { e.preventDefault(); } }; const onEnd = (e: globalThis.DragEvent) => { if (isFileDrag(e)) { e.preventDefault(); } depth = 0; setWindowDrag(false); setOverZone(0); }; window.addEventListener("dragenter", onEnter); window.addEventListener("dragleave", onLeave); window.addEventListener("dragover", onOver); window.addEventListener("drop", onEnd); window.addEventListener("dragend", onEnd); return () => { window.removeEventListener("dragenter", onEnter); window.removeEventListener("dragleave", onLeave); window.removeEventListener("dragover", onOver); window.removeEventListener("drop", onEnd); window.removeEventListener("dragend", onEnd); }; }, []); const validate = useCallback( (file: File): FileError | null => { if ( acceptedFileTypes.length && !acceptedFileTypes.some((type) => matchesAcceptedType(file, type)) ) { return { message: `Not ${describeAcceptedTypes(acceptedFileTypes)}`, code: "INVALID_FILE_TYPE", }; } if (file.size > maxFileSize) { return { message: `Larger than ${formatBytes(maxFileSize)}`, code: "FILE_TOO_LARGE", }; } return validateFile?.(file) ?? null; }, [acceptedFileTypes, maxFileSize, validateFile] ); const addFiles = useCallback( (fileList: FileList | File[] | null) => { const files = Array.from(fileList ?? []); if (!files.length) { return; } const { added, skipped } = buildItems(files, { room: Math.max(0, limit - counted), validate, nextId: () => { const index = nextIndex.current; nextIndex.current += 1; return { id: `${baseId}-${index}`, index }; }, }); for (const item of added) { if (item.previewUrl) { previewUrls.current.set(item.id, item.previewUrl); } if (item.error) { onUploadError?.(item.error, item.file); } } setNotice( skipped ? `${skipped} ${skipped === 1 ? "file was" : "files were"} not added. The limit is ${limit}.` : null ); if (added.length) { setItems((prev) => [...prev, ...added]); } }, [baseId, counted, limit, onUploadError, validate] ); const removeItem = useCallback( (id: string) => { controllers.current.get(id)?.abort(); controllers.current.delete(id); const url = previewUrls.current.get(id); if (url) { URL.revokeObjectURL(url); previewUrls.current.delete(id); } const item = items.find((i) => i.id === id); setItems((prev) => prev.filter((i) => i.id !== id)); setNotice(null); if (item) { onFileRemove?.(item.file); } }, [items, onFileRemove] ); const clearAll = useCallback(() => { for (const item of items) { removeItem(item.id); } }, [items, removeItem]); const retryItem = useCallback( (id: string) => updateItem(id, { status: "queued", progress: 0, error: undefined }), [updateItem] ); const openPicker = () => { if (!isFull) { inputRef.current?.click(); } }; const handleInputChange = (e: ChangeEvent) => { addFiles(e.target.files); e.target.value = ""; }; const handleZoneDrag = (e: DragEvent) => { if (!isFileDrag(e)) { return; } e.preventDefault(); e.dataTransfer.dropEffect = isFull ? "none" : "copy"; setOverZone(Math.max(1, countDraggedFiles(e.dataTransfer))); }; const handleZoneLeave = (e: DragEvent) => { if ( e.relatedTarget instanceof Node && e.currentTarget.contains(e.relatedTarget) ) { return; } setOverZone(0); }; const handleZoneDrop = (e: DragEvent) => { e.preventDefault(); setOverZone(0); setWindowDrag(false); if (!isFull) { addFiles(e.dataTransfer.files); } }; const handlePaste = (e: ClipboardEvent) => { if (e.clipboardData.files.length) { e.preventDefault(); addFiles(e.clipboardData.files); } }; const { done, failed, busy } = summarize(items); const { title, showBrowse, hint } = zoneCopy({ isFull, overZone, windowDrag, multiple, limit, maxFileSize, acceptedFileTypes, }); const armed = windowDrag && !isFull; const over = overZone > 0 && !isFull; return (

{notice && (

{notice}

)}

{items.map((item) => ( ))}

{items.length > 0 && (

{done}{" "} of {items.length} uploaded {failed > 0 && ( {" "} · {failed} failed )}

)}

); } FileUpload.displayName = "FileUpload";

File Upload

On this page