File Upload
A drag-and-drop file upload area with per-file progress tracking, validation, cancel, and retry.
Installation
dotnet add package Lumeo
One-time app setup (AddLumeo(), CSS & JS) is covered in the
installation guide.
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
Switch between Dropzone, Button, and Avatar to see the upload surface change.
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). |