BlazorBasics.InputFileExtended 3.9.46

BlazorBasics.InputFileExtended

Extend the traditional InputFile component with more options like drag and drop, copy and paste, preview, upload button, streaming for big files and a rich set of events — with less coding for everyone.

Official web documentation and live examples.

Supported target frameworks: .NET 8, .NET 9 and .NET 10.

Table of contents

• Features
• Installation
• Quick start
• Drag and drop
• Copy and paste
• Image preview
• Upload button
• Auto upload
• Streaming big files
• Events
  • OnSelected (new)
  • OnChange
  • OnAddFile
  • OnError
• Configuration reference
  • InputFileParameters
  • ButtonOptions
  • PreviewOptions
  • DragAndDropOptions
• Models
• Public members of the component
• Customizing the UI with RenderFragments

Features

• Standard file selection like the native InputFile.
• Drag and drop files into a drop zone.
• Copy and paste files / images from the clipboard.
• Image preview of the selected files.
• Optional upload button with before / after submit hooks.
• Auto upload after selection (one by one as an event callback).
• Streaming mode to upload very big files by chunks.
• Maximum number of files and maximum file size validation with detailed exceptions.
• Rich event model: OnSelected, OnChange, OnAddFile, OnError.
• Full UI customization through RenderFragment parameters.
• Works inside an EditForm (validated through the cascading EditContext).

Installation

Install from NuGet:

dotnet add package BlazorBasics.InputFileExtended

Import the namespace adding this line to _Imports.razor:

@using BlazorBasics.InputFileExtended

Tip: you can also import the value objects and models namespaces to avoid the long fully-qualified names used in some examples below:

@using BlazorBasics.InputFileExtended.ValueObjects
@using BlazorBasics.InputFileExtended.Models

Quick start

@using BlazorBasics.InputFileExtended

<InputFileComponent OnChange="LoadFiles" />

@code {
    private void LoadFiles(FilesUploadEventArgs e)
    {
        // e.Files  -> List<FileUploadContent>
        // e.Count  -> number of files
        // e.Size   -> total size in bytes
        // e.Action -> EventAction (Added, Removed, ...)
    }
}

Drag and drop

@using BlazorBasics.InputFileExtended
@using BlazorBasics.InputFileExtended.ValueObjects

<InputFileComponent Parameters="Parameters" OnChange="LoadFiles" />

@code {
    InputFileParameters Parameters = new()
    {
        DragAndDropOptions = new DragAndDropOptions
        {
            CanDropFiles = true
        }
    };

    private void LoadFiles(FilesUploadEventArgs e)
    {
        // ...
    }
}

Copy and paste

Paste works independently of drag and drop — you can enable either or both.

@using BlazorBasics.InputFileExtended
@using BlazorBasics.InputFileExtended.ValueObjects

<InputFileComponent Parameters="Parameters" OnChange="LoadFiles" />

@code {
    InputFileParameters Parameters = new()
    {
        AllowPasteFiles = true
    };

    private void LoadFiles(FilesUploadEventArgs e)
    {
        // ...
    }
}

Image preview

@using BlazorBasics.InputFileExtended
@using BlazorBasics.InputFileExtended.ValueObjects

<InputFileComponent Parameters="Parameters" OnChange="LoadFiles" />

@code {
    InputFileParameters Parameters = new()
    {
        PreviewOptions = new PreviewOptions
        {
            IsImage = true,
            ShowPreview = true,
            // Show a delete button even when there is no callback wired
            CanDeleteIfNotCallBack = true
        }
    };

    private void LoadFiles(FilesUploadEventArgs e) { }
}

When PreviewOptions.IsImage is true and no InputFileTypes is set, the input automatically restricts the selection to image/*.

Each selected file exposes a ready-to-use ImageDataUrl you can bind directly to an img element:

@foreach (var file in files)
{
    <img src="@file.ImageDataUrl" alt="@file.Name" />
}

Upload button

When you show the upload button, ButtonOptions.OnSubmit is required.

@using BlazorBasics.InputFileExtended
@using BlazorBasics.InputFileExtended.ValueObjects
@using BlazorBasics.InputFileExtended.Models

<InputFileComponent Parameters="Parameters" />

@code {
    InputFileParameters Parameters;

    protected override void OnInitialized()
    {
        Parameters = new InputFileParameters
        {
            ButtonOptions = new ButtonOptions
            {
                ButtonShow = true,
                ButtonTitle = "Upload",
                CleanOnSuccessUpload = true,
                OnBeforeSubmit = BeforeSubmit,
                OnSubmit = UploadFiles,
                OnAfterSubmit = AfterSubmit
            }
        };
    }

    Task BeforeSubmit(IReadOnlyList<FileUploadContent> files)
    {
        // e.g. show a spinner
        return Task.CompletedTask;
    }

    async Task UploadFiles(IReadOnlyList<FileUploadContent> files)
    {
        // process your upload, you have access to each file bytes
        foreach (var file in files)
        {
            byte[] bytes = file.FileBytes;
            // send to your API / storage ...
        }
        await Task.Delay(1);
    }

    Task AfterSubmit(bool isValid)
    {
        // e.g. hide the spinner, show a toast
        return Task.CompletedTask;
    }
}

Inside an EditForm, the button submit is validated against the cascading EditContext automatically. You can also trigger the submit programmatically by calling the public FormSave() method (see Public members).

Auto upload

With AutoUpload = true each file is uploaded right after it is selected (handled one by one through the submit callback), without showing a button.

@using BlazorBasics.InputFileExtended
@using BlazorBasics.InputFileExtended.ValueObjects
@using BlazorBasics.InputFileExtended.Models

<InputFileComponent Parameters="Parameters" />

@code {
    InputFileParameters Parameters;

    protected override void OnInitialized()
    {
        Parameters = new InputFileParameters
        {
            ButtonOptions = new ButtonOptions
            {
                AutoUpload = true,
                OnSubmit = UploadFiles
            }
        };
    }

    async Task UploadFiles(IReadOnlyList<FileUploadContent> files)
    {
        // ...
        await Task.Delay(1);
    }
}

Streaming big files

Enable EnableStreaming to handle very big files by chunks. In this mode the component reads only the file metadata on the .NET side and relies on the JavaScript layer to stream the content.

@using BlazorBasics.InputFileExtended
@using BlazorBasics.InputFileExtended.ValueObjects

<InputFileComponent Parameters="Parameters" OnChange="LoadFiles" />

@code {
    InputFileParameters Parameters = new()
    {
        EnableStreaming = true,
        MaxFileSize = 1024L * 1024L * 500L // 500 MB
    };

    private void LoadFiles(FilesUploadEventArgs e) { }
}

Events

All events are exposed as EventCallback parameters on InputFileComponent.

OnSelected

New. Raised the instant a selection is known (file name, size and content type), before any byte is read from disk. Use it to give immediate UI feedback (for example a "processing…" indicator) for heavy files such as videos, whose read can take several seconds.

The FileUploadContent items in the payload carry metadata only — FileBytes and ImageDataUrl are not populated yet. The reported Action is EventAction.Change.

Internally, when JavaScript is available, OnSelected fires from a native change listener the moment files are picked (even before Blazor's own change pipeline runs). If JS is unavailable it gracefully falls back to firing during the in-Change notification.

@using BlazorBasics.InputFileExtended
@using BlazorBasics.InputFileExtended.Models

<InputFileComponent OnSelected="HandleSelected" OnChange="HandleChange" />

@if (isProcessing)
{
    <p>Processing @pendingCount file(s)…</p>
}

@code {
    bool isProcessing;
    int pendingCount;

    // Fires immediately when the user picks files (metadata only, no bytes yet)
    private void HandleSelected(FilesUploadEventArgs e)
    {
        isProcessing = true;
        pendingCount = e.Count;

        foreach (var file in e.Files)
        {
            // file.Name, file.Size, file.ContentType, file.LastModified available
            // file.FileBytes is NOT available here yet
        }
    }

    // Fires later, once bytes are read and the files are added
    private void HandleChange(FilesUploadEventArgs e)
    {
        isProcessing = false;
        // Now e.Files contain the bytes (file.FileBytes / file.ImageDataUrl)
    }
}

OnChange

Raised once the selected files have been processed and added to the container, and also when a file is removed from the collection. The FileUploadContent items now contain the bytes.

<InputFileComponent OnChange="HandleChange" />

@code {
    private void HandleChange(FilesUploadEventArgs e)
    {
        switch (e.Action)
        {
            case EventAction.Added:   /* files added */    break;
            case EventAction.Removed: /* a file removed */ break;
        }
    }
}

OnAddFile

Raised per each individual file added, with a single-file payload. Useful together with auto upload to react file by file.

<InputFileComponent OnAddFile="HandleAddFile" />

@code {
    private void HandleAddFile(FileUploadEventArgs e)
    {
        FileUploadContent file = e.File;
        Guid id = e.FileId;
        EventAction action = e.Action;
    }
}

OnError

Raised when a validation rule (max file count, max size) or an upload fails. The InputFileException exposes detailed information about what went wrong.

<InputFileComponent Parameters="Parameters" OnError="HandleError" />

@code {
    InputFileParameters Parameters = new()
    {
        MaxUploatedFiles = 3,
        MaxFileSize = 1_048_576 // 1 MB
    };

    private void HandleError(InputFileException ex)
    {
        // ex.ExceptionType -> Generic | MaxCount | MaxSize (Flags)
        // ex.FilesCount, ex.FileBytes, ex.FileMbBytes
        // ex.MaxFilesAllowed, ex.MaxFileBytes, ex.MaxFileMbBytes
        // ex.Files -> files affected
        if (ex.ExceptionType.HasFlag(ExceptionType.MaxSize))
        {
            // show a friendly "file too big" message
        }
    }
}

If you do not wire OnError, the component shows the error message inline by itself.

Configuration reference

InputFileParameters

ButtonOptions

PreviewOptions

DragAndDropOptions

Models

FileUploadContent

The full representation of an uploaded file.

FileBasicInfo

Now public. Lightweight metadata model (no bytes), used by the streaming / early-selection pipeline and exposed publicly so you can consume it from your own code.

FilesUploadEventArgs

Payload for OnSelected and OnChange: Files (List<FileUploadContent>), Size (long), Count (int), Action (EventAction).

FileUploadEventArgs

Payload for OnAddFile: File (FileUploadContent), FileId (Guid), Action (EventAction).

EventAction

Change, Added, Updated, Removed, Clean, Upload.

Public members of the component

Capture a reference with @ref to access these:

<InputFileComponent @ref="inputFile" Parameters="Parameters" />

@code {
    InputFileComponent inputFile;

    void ClearAll() => inputFile.Clean();
    Task Save() => inputFile.FormSave();
    Task PickFiles() => inputFile.OpenFileDialog();
}

Customizing the UI with RenderFragments

InputFileComponent exposes several RenderFragment parameters to fully customize the UI:

<InputFileComponent Parameters="Parameters" OnChange="LoadFiles">
    <InputContent>
        <span>Drag your files here or click to browse</span>
    </InputContent>
    <ChildContent Context="file">
        <div class="file-row">
            <strong>@file.Name</strong> — @file.Size bytes
        </div>
    </ChildContent>
</InputFileComponent>

Made with ❤️ by DrUalcman. Issues and contributions are welcome at the GitHub repository.