# File Upload

A multi-file upload queue with per-file progress, retry and cancel.

Install with

```bash
npx shadcn@latest add https://kokonutui.com/r/file-upload.json
```

Drop files here or browse

Any file up to 5 MB · 5 max

## Installation

File Upload is a free, open-source React component in the Kokonut UI [Inputs collection](/content/docs/inputs/index.html). Add it with the shadcn CLI, which copies the source into `components/kokonutui/file-upload.tsx`, so the code is yours to change.

### Add via CLI

```bash
npx shadcn@latest add @kokonutui/file-upload
```

### Or add it by hand:
Install its packages, then copy the source from above into `components/kokonutui/file-upload.tsx`.

```bash
npm install lucide-react motion
```

## Usage

```javascript
import FileUpload from "@/components/kokonutui/file-upload";

export default function Example() {
  return <FileUpload />;
}
```

## Props

### `onUpload`
`(file: File, helpers: UploadHelpers) => Promise<void>`
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`.

### `onUploadSuccess`
`(file: File) => void`

### `onUploadError`
`(error: FileError, file: File) => void`
Called for validation errors and failed uploads.

### `onComplete`
`(files: File[]) => void`
Called with every uploaded file once nothing is queued or in flight.

### `onFileRemove`
`(file: File) => void`
Called when a row is removed (cancelling its upload if needed).

### `acceptedFileTypes`
`string[]`  Default `built-in`
MIME types ("image/png"), wildcards ("image/*") or extensions (".pdf").

### `maxFileSize`
`number`  Default `built-in`
Maximum size of each file in bytes. Defaults to 5 MB.

### `multiple`
`boolean`  Default `true`
Accept several files at once. Defaults to true.

### `maxFiles`
`number`  Default `5`
Maximum number of files in the list. Defaults to 5.

### `uploadDelay`
`number`  Default `2000`
Simulated upload duration per file in ms, used without `onUpload`.

### `simulateFailure`
`boolean`  Default `false`
Simulated uploads only: the first attempt of every third file fails.

### `validateFile`
`(file: File) => FileError | null`

### `className`
`string`
Extra classes for the root element.

### UploadHelpers

#### `onProgress`
`(percent: number) => void`
Required. Report upload progress from 0 to 100.

#### `signal`
`AbortSignal`
Required. Aborted when the row is removed or the component unmounts.

### FileError

#### `message`
`string`  Required.

#### `code`
`string`  Required.

## Dependencies

| Needs | Version | Comes from |
| --- | --- | --- |
| `lucide-react` | `^0.556.0` | npm, installed by the CLI |
| `motion` | `^12.23.25` | npm, installed by the CLI |
| `cn` from `lib/utils.ts` |  | shadcn init |
| React | `19` | Your app |
| Tailwind CSS | `4` | Your app |

No provider, font or global CSS to set up: the file works as soon as it lands.
