Photonix

FileUpload

A premium drag-and-drop component for file uploads with progress tracking and list management.

Preview

Upload assets choose files
PNG, JPG, or PDF up to 10 MB
Usage
"use client";

import { useState } from 'react';
import { FileUpload, type FileItem } from '@photonix/ultimate';

export default function FileUploadBasicExample() {
    const [files, setFiles] = useState<FileItem[]>([]);

    return (
        <FileUpload
            files={files}
            onFilesChange={setFiles}
            accept="image/*,.pdf"
            mediaType="image"
            variant="default"
            size="md"
            title="Upload assets"
            subtitle="PNG, JPG, or PDF up to 10 MB"
            maxSize={10 * 1024 * 1024}
        />
    );
}

Component API

FileUpload

Prop
Type
Default
Description
files
FileItem[]
-
Controlled list of files
onFilesChange
(files: FileItem[]) => void
-
Callback when files change
accept
string
-
Accepted file types (e.g. "image/*, .pdf")
multiple
boolean
true
Allow multiple files selection
maxSize
number
-
Maximum file size in bytes
size
"sm" | "md" | "lg"
'lg'
Visual size variant
variant
"default" | "square"
'default'
Layout variant for the upload surface and selected items
mediaType
"image" | "video" | "file"
'file'
Primary upload media type
disabled
boolean
false
Disabled state
title
string
-
Custom title for drop zone
subtitle
string
-
Custom subtitle for drop zone. Defaults are derived from mediaType and maxSize.
className
string
-
Additional class name

Variants

Sizes

Use size variants to match the density of the surrounding layout. `lg` keeps the original upload surface, while `md` and `sm` provide more compact options.

Compact upload choose files
Fits tool panels and smaller forms
Medium upload choose files
A reduced footprint for denser forms
Default upload choose files
Preserves the original FileUpload size
Sizes
"use client";

import { FileUpload, Flex } from '@photonix/ultimate';

export default function FileUploadSizesExample() {
    return (
        <Flex direction="column" gap="md" w="100%" maxW={560}>
            <FileUpload size="sm" title="Compact upload" subtitle="Fits tool panels and smaller forms" files={[]} onFilesChange={() => {}} />
            <FileUpload size="md" title="Medium upload" subtitle="A reduced footprint for denser forms" files={[]} onFilesChange={() => {}} />
            <FileUpload size="lg" title="Default upload" subtitle="Preserves the original FileUpload size" files={[]} onFilesChange={() => {}} />
        </Flex>
    );
}

Media Types

Switch the component between generic files, images, and video uploads. This updates the icon language and default helper copy.

Documents and attachments choose files
PDF, DOCX, ZIP. File size max 25 MB
Image upload choose files
JPG, PNG, WebP. File size max 25 MB
Video upload choose files
MP4, MOV, WebM. File size max 250 MB
Media Types
"use client";

import { FileUpload, Flex } from '@photonix/ultimate';

export default function FileUploadMediaExample() {
    return (
        <Flex direction="column" gap="md" w="100%" maxW={560}>
            <FileUpload mediaType="file" title="Documents and attachments" subtitle="PDF, DOCX, ZIP. File size max 25 MB" files={[]} onFilesChange={() => {}} />
            <FileUpload mediaType="image" accept="image/png,image/jpeg,image/webp" title="Image upload" subtitle="JPG, PNG, WebP. File size max 25 MB" files={[]} onFilesChange={() => {}} />
            <FileUpload mediaType="video" accept="video/mp4,video/quicktime,video/webm" title="Video upload" subtitle="MP4, MOV, WebM. File size max 250 MB" files={[]} onFilesChange={() => {}} />
        </Flex>
    );
}

Square Variant

Use the square variant for avatar pickers, cover uploads, and media-first flows. Selected items switch to Attachment cards automatically.

Image choose file
JPG, PNG
Video choose file
MP4, MOV
Square Variant
"use client";

import { Box, FileUpload, Flex } from '@photonix/ultimate';

export default function FileUploadSquareExample() {
    return (
        <Flex gap="md" wrap="wrap" align="start">
            <Box w={160}>
                <FileUpload variant="square" size="lg" mediaType="image" accept="image/png,image/jpeg,image/webp" multiple={false} title="Image" subtitle="JPG, PNG" files={[]} onFilesChange={() => {}} />
            </Box>
            <Box w={136}>
                <FileUpload variant="square" size="md" mediaType="video" accept="video/mp4,video/quicktime,video/webm" multiple={false} title="Video" subtitle="MP4, MOV" files={[]} onFilesChange={() => {}} />
            </Box>
        </Flex>
    );
}

Multiple vs Single

Control whether users can upload one or multiple files. In single mode, the drop zone is hidden once a file is selected.

Default (Multiple) choose files
PDF, DOCX, ZIP. File size max 25 MB
Single Mode choose file
Selecting a file replaces the current one
Multiple vs Single
"use client";

import { FileUpload, Flex } from '@photonix/ultimate';

export default function FileUploadMultipleExample() {
    return (
        <Flex direction="column" gap="md" w="100%" maxW={400}>
            <FileUpload title="Default (Multiple)" files={[]} onFilesChange={() => {}} />
            <FileUpload title="Single Mode" subtitle="Selecting a file replaces the current one" multiple={false} files={[]} onFilesChange={() => {}} />
        </Flex>
    );
}

File Items & Status

Demonstrates how different file statuses (Uploading, Success, Error) are rendered in the list.

Upload Progress choose files
PDF, DOCX, ZIP. File size max 25 MB
presentation.pdf0 B
vacation-photo.jpg
large-video.mp4File size exceeds 25MB limit
File Items & Status
"use client";

import { FileUpload, type FileItem } from '@photonix/ultimate';

const mockFiles: FileItem[] = [
    { id: '1', file: new File([''], 'presentation.pdf', { type: 'application/pdf' }), status: 'success', progress: 100 },
    { id: '2', file: new File([''], 'vacation-photo.jpg', { type: 'image/jpeg' }), status: 'uploading', progress: 45 },
    { id: '3', file: new File([''], 'large-video.mp4', { type: 'video/mp4' }), status: 'error', progress: 0, error: 'File size exceeds 25MB limit' },
];

export default function FileUploadStatusExample() {
    return <FileUpload title="Upload Progress" files={mockFiles} onFilesChange={() => {}} />;
}

Accepted File Types

Restrict uploads to specific file types using the standard HTML accept attribute.

Images Only choose files
Only PNG and JPG files are allowed
Accepted File Types
"use client";

import { FileUpload } from '@photonix/ultimate';

export default function FileUploadTypesExample() {
    return <FileUpload title="Images Only" accept="image/png, image/jpeg" subtitle="Only PNG and JPG files are allowed" files={[]} onFilesChange={() => {}} />;
}

States

The disabled state prevents all interactions including dragging and clicking.

Upload Disabled choose files
PDF, DOCX, ZIP. File size max 25 MB
States
"use client";

import { FileUpload } from '@photonix/ultimate';

export default function FileUploadStatesExample() {
    return <FileUpload disabled title="Upload Disabled" files={[]} onFilesChange={() => {}} />;
}

On this page

Preview
Component API
Variants
Sizes
Media Types
Square Variant
Multiple vs Single
File Items & Status
Accepted File Types
States
Photonix UI - React Components, Templates & Figma Design System