FileUploader

File upload component with drag-and-drop and progress tracking

Overview

FileUploader provides a complete file upload experience with drag-and-drop support, progress tracking, and automatic integration with the Files API. It supports multiple file presets (image, document, video, audio) with appropriate size limits.

Key Features

Drag-and-drop file selection with visual feedback
Upload progress bar with file preview
Automatic Files API integration via Vercel Blob
Configurable presets for different file types

Examples

Default

Full-size vertical layout for dedicated upload areas, onboarding flows, and empty states.

Compact

Smaller vertical layout with tighter spacing for constrained spaces.

Inline

Horizontal layout for form rows, alongside other inputs, and tight spaces.

Props Reference

Prop	Type	Default	Description
`preset`	`'image' \| 'document' \| 'video' \| 'audio'`	`required`	File type preset defining accepted types and size limits
`purpose`	`FilePurpose`	`required`	File purpose: DESIGN, CONTENT, ATTACHMENT, or AVATAR
`accessLevel`	`FileAccess`	`required`	Access level: PUBLIC, PROGRAM, or PROJECT
`onUploadComplete`	`(file: FileDTO) => void`	`required`	Callback when upload succeeds with file data
`scopeType`	`'PROGRAM' \| 'PROJECT'`	`-`	Optional scope type for file association
`scopeId`	`string`	`-`	Optional scope ID for file association
`maxSizeOverride`	`number`	`-`	Override the preset's max file size in bytes
`onUploadError`	`(error: Error) => void`	`-`	Optional callback when upload fails
`variant`	`'default' \| 'compact' \| 'inline'`	`default`	Layout variant: default (full), compact (smaller), or inline (horizontal)
`disabled`	`boolean`	`false`	Disable the uploader

Usage

import { FileUploader } from '@/ui/components';

// Basic image upload
<FileUploader
  preset="image"
  purpose="DESIGN"
  accessLevel="PUBLIC"
  onUploadComplete={handleUpload}
/>

// With scope context (for library queries)
<FileUploader
  preset="image"
  purpose="DESIGN"
  accessLevel="PUBLIC"
  scopeType="PROGRAM"
  scopeId={programId}
  onUploadComplete={handleUpload}
  onUploadError={(error) => console.error(error)}
/>

// Document upload with custom size limit
<FileUploader
  preset="document"
  purpose="ATTACHMENT"
  accessLevel="PROJECT"
  scopeType="PROJECT"
  scopeId={projectId}
  maxSizeOverride={50 * 1024 * 1024} // 50MB
  onUploadComplete={handleUpload}
/>

Prop

Type

Default

Description

preset

'image' | 'document' | 'video' | 'audio'

required

File type preset defining accepted types and size limits

purpose

FilePurpose

required

File purpose: DESIGN, CONTENT, ATTACHMENT, or AVATAR

accessLevel

FileAccess

required

Access level: PUBLIC, PROGRAM, or PROJECT

onUploadComplete

(file: FileDTO) => void

required

Callback when upload succeeds with file data

scopeType

'PROGRAM' | 'PROJECT'

-

Optional scope type for file association

scopeId

string

-

Optional scope ID for file association

maxSizeOverride

number

-

Override the preset's max file size in bytes

onUploadError

(error: Error) => void

-

Optional callback when upload fails

variant

'default' | 'compact' | 'inline'

default

Layout variant: default (full), compact (smaller), or inline (horizontal)

disabled

boolean

false

Disable the uploader

import { FileUploader } from '@/ui/components'; // Basic image upload <FileUploader preset="image" purpose="DESIGN" accessLevel="PUBLIC" onUploadComplete={handleUpload} /> // With scope context (for library queries) <FileUploader preset="image" purpose="DESIGN" accessLevel="PUBLIC" scopeType="PROGRAM" scopeId={programId} onUploadComplete={handleUpload} onUploadError={(error) => console.error(error)} /> // Document upload with custom size limit <FileUploader preset="document" purpose="ATTACHMENT" accessLevel="PROJECT" scopeType="PROJECT" scopeId={projectId} maxSizeOverride={50 * 1024 * 1024} // 50MB onUploadComplete={handleUpload} />