# File Upload

Source: https://lumeo.nativ.sh/components/file-upload

# File Upload

A drag-and-drop file upload area with per-file progress tracking, validation, cancel, and retry.

## Installation

.NET CLI PackageReference Lumeo CLI

dotnet add package Lumeo

One-time app setup (`AddLumeo()`, CSS & JS) is covered in the [installation guide](docs/introduction).

## Usage

@using Lumeo

<FileUpload />

## When to Use

-   File attachments in forms such as resumes, invoices, or supporting documents
-   Image uploads for profile pictures, product photos, or galleries
-   Document submissions with drag-and-drop zones for a better user experience
-   Bulk file uploads with per-file progress indicators, cancel, and retry

Preview Code

Default

Click to upload or drag and drop

Preview Code

Image Upload

Upload an image

Upload an image

PNG, JPG or GIF up to 10MB

Preview Code

Multiple Files

Upload documents

Upload documents

Select one or more files

Preview Code

Upload with progress (fake delay)

Upload files

Upload files

Each file uploads with simulated progress

Preview Code

Manual upload trigger (AutoUpload=false)

Choose files, then click Upload

Choose files, then click Upload

Preview Code

With Progress (legacy)

Upload Images

Upload Images

PNG, JPG up to 10MB

Preview Code

Variant — interactive preview

Switch between Dropzone, Button, and Avatar to see the upload surface change.

Dropzone Button Avatar

Upload file

Upload file

PNG, JPG or PDF up to 10MB

## API Reference

### FileUpload

Prop

Type

Default

Description

Label

string?

null

Primary label text shown in the drop zone.

Description

string?

null

Secondary description text shown below the label.

Multiple

bool

false

Allows selecting multiple files at once.

Accept

string?

null

File types accepted (e.g. "image/\*", ".pdf,.docx").

MaxFileSize

long

10 MB

Maximum allowed file size in bytes.

MaxFiles

int

10

Maximum number of files when Multiple is true.

ShowThumbnails

bool

false

Shows image thumbnails for uploaded image files.

FileTemplate

RenderFragment<IBrowserFile>?

null

Custom template for rendering each selected file row (overrides default per-file UI).

Variant

FileUpload.FileUploadVariant

Dropzone

Upload style variant. Values: `Dropzone`, `Button`, `Avatar`.

Size

Lumeo.Size

Default

Button size for `Variant=Button`. Values: `Sm`, `Default`, `Lg`.

OnFilesSelected

EventCallback<InputFileChangeEventArgs>

—

Fires when files are selected (raw args, kept for back-compat).

OnUpload

Func<FileUploadItem, IProgress<int>, CancellationToken, Task<string?>>?

null

Upload handler called per file. Report percent via IProgress, return the server URL/id on success, or throw on failure.

AutoUpload

bool

true

Start uploads immediately after selection. Set false to show an explicit Upload button.

MaxConcurrentUploads

int

3

Maximum number of simultaneous OnUpload calls.

ChunkSize

long?

null

Optional chunk-size hint (bytes) passed to each FileUploadItem for consumers implementing chunked upload.

OnFileUploaded

EventCallback<FileUploadItem>

—

Fires when a single file upload succeeds.

OnAllUploaded

EventCallback<IReadOnlyList<FileUploadItem>>

—

Fires when all queued uploads finish (succeeded, failed, or cancelled).

OnFileFailed

EventCallback<FileUploadItem>

—

Fires when a file upload fails.

OnFileRemoved

EventCallback<FileUploadItem>

—

Fires when a file is removed from the list.

OnFileRejected

EventCallback<(IBrowserFile, string)>

—

Fires when a file is rejected by validation (size / type / count).

MaxFileSizeError

string?

null

Custom error message when a file exceeds MaxFileSize.

MaxFilesError

string?

null

Custom error message when MaxFiles is exceeded.

FileTypeError

string?

null

Custom error message when a file type doesn't match Accept.

ShowProgress

bool

false

Legacy: shows a global progress bar (only when OnUpload is not set).

Progress

int

0

Legacy: global upload progress % (0–100). Superseded by per-file tracking when OnUpload is set.

Class

string?

null

Additional CSS classes on the root element.

AdditionalAttributes

Dictionary<string, object>?

null

Additional HTML attributes forwarded to the root element.

Required

bool

false

Marks the field as required for form validation.

Invalid

bool

false

Applies a destructive ring to indicate a validation error.

ErrorText

string?

null

Error message shown below when Invalid is true (standalone, not inside FormField).

HelperText

string?

null

Help text shown below when there is no error (standalone).

Name

string?

null

HTML name attribute for form identification.

FormField

FormFieldContext?

null

Cascaded context from a parent FormField; drives validation state automatically.

### FileUploadItem

Represents the state of each file in the upload queue. Passed to `OnUpload`, `OnFileUploaded`, `OnFileFailed`, etc.

Property

Type

Description

Id

string

Unique identifier (Guid hex) for this upload item.

File

IBrowserFile

The underlying browser file reference.

Name

string

File name.

Size

long

File size in bytes.

Status

FileUploadStatus

Current status: `Pending`, `Uploading`, `Succeeded`, `Failed`, `Cancelled`.

ProgressPercent

int

Upload progress 0–100, updated via IProgress.

ErrorMessage

string?

Error message if Status is Failed.

Url

string?

Server-returned URL or id after a successful upload.

ChunkSize

long

Chunk-size hint from the `ChunkSize` parameter (0 if not set).

## Related Components

-   [Input](/components/input) — For standard text and data entry fields
-   [Button](/components/button) — For triggering file selection via a button-style upload
-   [Progress](/components/progress) — For showing upload progress as a standalone bar