File Picker

Pro

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.

Preview

Installation

npx @lumioui/cli add pro/file-picker

Usage

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

Also exported: formatBytes, FILE_SETTLE_MS, FileRow, FileTile.

Examples

Expense receipts

An expense report in a corporate card app.

Listing photos

"Sell a bundle" in a secondhand fashion app.

Bug report

A notes app's "Report a problem" form.

API reference

FileRow

Prop Type Default
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.

 0
onPreview (file: FileItem, index: number) => void

Tap an image/video thumbnail to preview it (lightbox, full-screen viewer).

 —
renderThumbnail
(file: FileItem, context: FileThumbnailC … (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 Default
tag string

Small label pinned on the tile (e.g. "Cover").

 —

FilePicker

Prop Type Default
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.

 DEFAULT_SOURCES
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: FileThumbnailC … (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".

 "list"
columns number

Grid columns. Default 3.

 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 —