Skip to content

armgit / ui

Public Imported from GitHub
0
TypeScript
4.1 KB
Raw Blame
---
title: File Upload
description: Upload, validate, and queue documents with drag-and-drop, file type rules, progress states, and retry handling.
component: true
featured: true
---

File Upload is the starting point for document processing workflows. It should help users get files into the system quickly while making validation, progress, and failure states clear.

<FileUploadDemo />

## Installation

<CodeTabs>

<TabsList>
  <TabsTrigger value="cli">Command</TabsTrigger>
  <TabsTrigger value="manual">Manual</TabsTrigger>
</TabsList>
<TabsContent value="cli">

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

</TabsContent>

<TabsContent value="manual">

<Steps className="mb-0 pt-2">

<Step>Install the following dependencies:</Step>

```bash
npm install border-beam@^1.0.1
```

<Step>Install the icon library configured in your `components.json`:</Step>

The component source references icons through the shadcn CLI's
`IconPlaceholder`, which supports every `iconLibrary` the CLI does: `lucide`,
`tabler`, `hugeicons`, `phosphor`, and `remixicon`. Installing with the CLI
replaces each placeholder with the matching icon from your configured library,
so make sure that library's package is installed. When copying the source
manually, replace each `IconPlaceholder` element with the icon named by the
prop for your library.

<Step>
  Install the File Thumbnail component because File Upload uses it for selected
  file rows.
</Step>

```bash
npx shadcn@latest add @extend/file-thumbnail
```

<Step>Copy and paste the following code into your project.</Step>

<FileUploadSource />

<Step>Update the import paths to match your project setup.</Step>

</Steps>

</TabsContent>

</CodeTabs>

## Useful behaviors

- Drag-and-drop and file picker entrypoints.
- File type, size, page count, and duplicate validation.
- Upload progress, cancel, retry, and queued states.
- Batch upload summaries for mixed PDFs, DOCX files, Excel workbooks, images, and CSVs.
- Hooks for parsing, extraction, review, or routing once files are accepted.

## API Reference

### FileUpload

The FileUpload component renders a drag-and-drop file picker, validates accepted files, and keeps an internal upload queue unless you mirror it through callbacks.

| Prop                | Type                                               | Default                                   | Required |
| ------------------- | -------------------------------------------------- | ----------------------------------------- | -------- |
| `accept`            | `string`                                           | PDF, DOC/DOCX, XLSX, CSV, PNG, or JPG     | No       |
| `acceptedFileTypes` | `AcceptedFileType[]`                               | Image, PDF, and Sheet icons               | No       |
| `borderBeamTheme`   | `React.ComponentProps<typeof BorderBeam>["theme"]` | `"light"`                                 | No       |
| `browseLabel`       | `string`                                           | `"Browse files"`                          | No       |
| `className`         | `string`                                           | `-`                                       | No       |
| `description`       | `string`                                           | `"PDF, DOC/DOCX, XLSX, CSV, PNG, or JPG"` | No       |
| `draggingLabel`     | `string`                                           | `"Drop to add"`                           | No       |
| `multiple`          | `boolean`                                          | `true`                                    | No       |
| `showBorderBeam`    | `boolean`                                          | `true`                                    | No       |
| `showFileList`      | `boolean`                                          | `true`                                    | No       |
| `title`             | `string`                                           | `"Click to upload or drop files"`         | No       |
| `onFilesAccepted`   | `(files: File[]) => void`                          | `-`                                       | No       |
| `onFilesChange`     | `(files: FileUploadItem[]) => void`                | `-`                                       | No       |