File Upload

The default FileUpload renders a dropzone with a dashed border that accepts a single file via click or drag-and-drop. Bind to an IReadOnlyList<FileUploadItem>? with @bind-Files for two-way data binding. Image files automatically display a thumbnail preview.

Set Multiple to true and Accept to image/* to allow multi-file image uploads. Use MaxFileCount to limit the total number of files. Each uploaded image shows a thumbnail preview with a remove button, making it easy to manage the selection before submission.

Use the Accept parameter with file extensions like .pdf,.doc,.docx to restrict uploads to specific document types. Combine with MaxFileSize to set a custom size limit — this example allows up to 20MB per file. Non-matching files are automatically rejected with a validation error.

Use the OnValidationError callback to handle validation failures such as file size exceeded, unsupported file type, or maximum file count reached. The callback receives a FileValidationError with a Message property describing the issue, which you can display to the user.

Set ShowPreview to false to hide image thumbnail previews. Files still appear in a list with their name and size, but without the visual thumbnail. This is useful for non-image file uploads or when you want a more compact upload interface.

Use the Class parameter to apply custom Tailwind CSS classes to the dropzone container. This example shows a wider dropzone with a primary border accent and gradient background, useful for hero upload areas or prominent file attachment sections in forms.

Set Disabled to true to prevent user interaction. The dropzone renders with reduced opacity, and both click and drag-and-drop interactions are blocked. This is suitable for locked form fields or when file uploads are temporarily unavailable.

A real-world composition showing the FileUpload as a profile picture uploader within a settings card. The upload is restricted to a single image file with a 5MB limit. This pattern is common in account settings, user profile pages, and onboarding flows.

Set UploadHandler and the component stops being a plain selector: every row gains a <progress> bar, a status message, and an Upload, Cancel or Retry button. Your handler owns the transport — read the file with OpenReadStream(), report cumulative bytes with ReportProgressAsync, and observe the CancellationToken. Returning normally marks the file Succeeded; throwing marks it Failed and offers Retry. At most three uploads run at once; the rest wait as Queued. The demo below throttles a real browser stream instead of sending it anywhere.

AutoUpload="false" leaves selected files in the Selected state until you start them. Capture the component with @ref and call UploadFilesAsync() to start everything, UploadFileAsync(file) for one file, or ClearFiles() to cancel and reset. Browser file references stay valid across later selections, so a queued, failed or canceled file can still be retried.