# File Picker

Attachment field with photo, camera and document buttons for your app’s pickers, showing uploads as a list or grid. Each file shows its progress, ticks when done and flags failures.

> Composed · Pro · Forms & Inputs — React Native, Expo Go compatible.

## Install

```bash
npx @lumioui/cli add pro/file-picker
```

## Import

```tsx
import { formatBytes, FILE_SETTLE_MS, FileRow, FileTile, FilePicker } from "@/components/ui/file-picker/file-picker";
```

## Variants

- `expense` — Expense receipts: `npx @lumioui/cli add pro/file-picker-expense`
- `listing` — Listing photos: `npx @lumioui/cli add pro/file-picker-listing`
- `support` — Bug report: `npx @lumioui/cli add pro/file-picker-support`

## Props

### FileRow

| Prop | Type | Notes |
| --- | --- | --- |
| `file` | `FileItem` | — |
| `onRemove?` | `(id: string) => void` | — |
| `onRetry?` | `(id: string) => void` | — |
| `onPress?` | `(file: FileItem) => void` | — |
| `index?` | `number` | Position in the list — passed back to `onPreview` / `renderThumbnail`. Default 0. |
| `onPreview?` | `(file: FileItem, index: number) => void` | Tap an image/video thumbnail to preview it (lightbox, full-screen viewer). |
| `renderThumbnail?` | `(file: FileItem, context: FileThumbnailContext) => React.ReactNode` | Render an image/video thumbnail yourself — e.g. a LightboxImage. Fill the box (`h-full w-full`); the node owns its own taps. Default: a cover Image. |

### FileTile

| Prop | Type | Notes |
| --- | --- | --- |
| `tag?` | `string` | Small label pinned on the tile (e.g. "Cover"). |

### FilePicker

| Prop | Type | Notes |
| --- | --- | --- |
| `files` | `FileItem[]` | Attached files (controlled — you own picking and uploading). |
| `onPickSource?` | `(key: string) => void` | Fires with a source key when a source tile is tapped. |
| `sources?` | `FileSource[]` | Source tiles. Default Photos / Camera / Files. Pass [] to hide. |
| `onRemove?` | `(id: string) => void` | Remove handler — shows an × on each file. |
| `onRetry?` | `(id: string) => void` | Retry handler for failed uploads. |
| `onFilePress?` | `(file: FileItem) => void` | Row / tile press (preview). |
| `onPreview?` | `(file: FileItem, index: number) => void` | Tap an image/video thumbnail to preview it — the list thumb and the grid tile. On grid tiles it wins over `onFilePress` for finished uploads. |
| `renderThumbnail?` | `(file: FileItem, context: FileThumbnailContext) => React.ReactNode` | Render image/video thumbnails yourself (e.g. a LightboxImage). Default: a cover Image. |
| `layout?` | `"list" | "grid"` | "list" rows in a card (documents) or "grid" thumbnails (photos).  Default "list". |
| `columns?` | `number` | Grid columns. Default 3. |
| `maxFiles?` | `number` | Cap — source tiles disable (with a warning haptic) once reached. |
| `label?` | `string` | Label above the field. |
| `helper?` | `string` | Hint under the field ("PDF, JPG up to 10 MB"). |
| `firstTag?` | `string` | Tag the first grid tile (e.g. "Cover"). |
| `className?` | `string` | — |

## Icons rendered

- `image` — /icons.html?i=image
- `camera` — /icons.html?i=camera
- `file-text` — /icons.html?i=file-text
- `x` — /icons.html?i=x
- `refresh` — /icons.html?i=refresh

Source: https://lumioui.com/components/file-picker