Class SfUploader

The Syncfusion Blazor Uploader component provides a comprehensive file upload solution with advanced features for uploading images, documents, and other files to a server. This component extends the functionality of HTML5 file upload with multiple file selection, automatic upload, drag and drop support, progress tracking, file preloading, and validation capabilities.

Inheritance

System.Object

SfBaseComponent

SfUploader

Inherited Members

SfBaseComponent.Dispose()

SfBaseComponent.Dispose(Boolean)

SfBaseComponent.GetEffectivePlatform()

SfBaseComponent.GetMainComponentPlatform()

SfBaseComponent.IsMainLicenseComponent()

SfBaseComponent.LicenseContext

SfBaseComponent.OnAfterRenderAsync(Boolean)

SfBaseComponent.OnInitializedAsync()

SfBaseComponent.OnObservableChange(String, Object, Boolean, NotifyCollectionChangedEventArgs)

SfBaseComponent.ValidateLicense()

Namespace: Syncfusion.Blazor.Inputs

Assembly: Syncfusion.Blazor.dll

Syntax

public class SfUploader : SfBaseComponent

Remarks

The SfUploader component offers a rich set of features including:

• Multiple file selection and upload
• Drag and drop functionality for intuitive file selection
• Automatic upload with configurable settings
• Progress bar visualization during upload operations
• File validation with size and type restrictions
• Template customization for enhanced user experience
• Chunk upload support for large files
• Resume and pause upload functionality

The component integrates seamlessly with server-side upload handlers and provides comprehensive event handling for upload lifecycle management.

Examples

Basic implementation of the SfUploader component:

<SfUploader ID="fileUpload" AutoUpload="false">
    <UploaderAsyncSettings SaveUrl="api/SampleData/Save" RemoveUrl="api/SampleData/Remove" />
    <UploaderEvents OnUploadStart="@OnFileUploadStart" ValueChange="@OnChange" />
</SfUploader>

@code {
    private void OnFileUploadStart(UploadingEventArgs args)
    {
        // Handle upload start logic
    }

    private void OnChange(UploadChangeEventArgs args)
    {
        // Handle file selection changes
    }
}

Constructors

SfUploader()

Declaration

public SfUploader()

Properties

AllowedExtensions

Gets or sets the internal storage for allowed extensions property.

Declaration

public string AllowedExtensions { get; set; }

Property Value

Type	Description
System.String	Accepts the string value. The default value is empty.

Remarks

For example, if you want to upload specific image files, pass the property as ".jpg" and ".png."

Examples

@using Syncfusion.Blazor.Inputs
<SfUploader ID="UploadFiles" AllowedExtensions=".jpg, .png">
    <UploaderAsyncSettings SaveUrl="api/SampleData/Save" RemoveUrl="api/SampleData/Remove"/>
</SfUploader>

AllowMultiple

Gets or sets the internal storage for AllowMultiple property.

Declaration

public bool AllowMultiple { get; set; }

Property Value

Type	Description
System.Boolean	true if multiple file selection is enabled; otherwise, false. The default value is true.

AutoUpload

Gets or sets the internal storage for AutoUpload property.

Declaration

public bool AutoUpload { get; set; }

Property Value

Type	Description
System.Boolean	true, if the automatic upload option can be enabled in component. Otherwise, false. The default value is true.

Remarks

If you want to manipulate the files before uploading to server, disable the AutoUpload property.

Examples

@using Syncfusion.Blazor.Inputs
<SfUploader ID="UploadFiles" AutoUpload="false">
    <UploaderAsyncSettings SaveUrl="api/SampleData/Save" RemoveUrl="api/SampleData/Remove" />
</SfUploader>

CssClass

Gets or sets the internal storage for CssClass property.

Declaration

public string CssClass { get; set; }

Property Value

Type	Description
System.String	Accepts the CSS class string separated by space to customize the appearance of component.

Remarks

One or more custom CSS classes can be added to a file upload.

Examples

@using Syncfusion.Blazor.Inputs
<SfUploader ID="UploadFiles" CssClass="custom-uploader my-class">
    <UploaderAsyncSettings SaveUrl="api/SampleData/Save" RemoveUrl="api/SampleData/Remove" />
</SfUploader>

DirectoryUpload

Gets or sets the internal storage for DirectoryUpload property.

Declaration

public bool DirectoryUpload { get; set; }

Property Value

Type	Description
System.Boolean	true if directory upload is enabled; otherwise, false. The default value is false.

DropArea

Gets or sets the internal storage for DropArea property.

Declaration

public string DropArea { get; set; }

Property Value

Type	Description
System.String	Accepts the target element selector string.

Remarks

By default, the file upload component creates a container element around the file input that will act as a drop target.

Examples

@using Syncfusion.Blazor.Inputs
<SfUploader DropArea="#CustomDropArea" >
    <UploaderAsyncSettings SaveUrl="api/SampleData/Save" RemoveUrl="api/SampleData/Remove" />
</SfUploader>
<div id="CustomDropArea" style="width:200px; height:200px; border:dashed 1px" ></div>

DropEffect

Gets or sets the internal storage for DropEffect property.

Declaration

public DropEffect DropEffect { get; set; }

Property Value

Type	Description
DropEffect	One of the DropEffect enumeration that specifies the drag operation for the component. The default value is Default.

Remarks

The DropEffect property can be set to one of the following values:

• Copy
• Move
• Link
• None

Examples

@using Syncfusion.Blazor.Inputs
<SfUploader ID="UploadFiles" DropEffect="DropEffect.Copy">
    <UploaderAsyncSettings SaveUrl="api/SampleData/Save" RemoveUrl="api/SampleData/Remove" />
</SfUploader>

Enabled

Gets or sets the internal storage for Enabled property.

Declaration

public bool Enabled { get; set; }

Property Value

Type	Description
System.Boolean	true if the user can interact with the component; otherwise, false. The default value is true.

EnableHtmlSanitizer

Gets or sets the internal storage for EnableHtmlSanitizer property.

Declaration

public bool EnableHtmlSanitizer { get; set; }

Property Value

Type	Description
System.Boolean	true if the component prevents cross-site scripting code in filenames; otherwise, false. The default value is true.

Remarks

The EnableHtmlSanitizer property removes cross-site scripting code or functions from the filename and shows a validation error message to the user.

Examples

@using Syncfusion.Blazor.Inputs
<SfUploader ID="UploadFiles" EnableHtmlSanitizer="false">
    <UploaderAsyncSettings SaveUrl="api/SampleData/Save" RemoveUrl="api/SampleData/Remove" />
</SfUploader>

EnablePersistence

Gets or sets the internal storage for EnablePersistence property.

Declaration

public bool EnablePersistence { get; set; }

Property Value

Type	Description
System.Boolean	true if persistence is enabled; otherwise, false. The default value is false.

EnableRtl

Gets or sets the internal storage for EnableRtl property.

Declaration

public bool EnableRtl { get; set; }

Property Value

Type	Description
System.Boolean	true if right-to-left direction is enabled for the component; otherwise, false. The default value is false.

HtmlAttributes

Gets or sets an additional html attributes such as styles, class, and more to add the root element.

Declaration

public Dictionary<string, object> HtmlAttributes { get; set; }

Property Value

Type	Description
System.Collections.Generic.Dictionary<System.String, System.Object>	A dictionary of additional HTML attributes for the root element of the component.

Remarks

If you configured both property and equivalent html attributes, the component considers the property value.

Examples

@using Syncfusion.Blazor.Inputs
<SfUploader ID="UploadFiles" HtmlAttributes="@HtmlAttribute">
    <UploaderAsyncSettings SaveUrl="api/SampleData/Save" RemoveUrl="api/SampleData/Remove" />
</SfUploader>
@code {
    Dictionary<string, object> HtmlAttribute = new Dictionary<string, object>() {
    {"disabled","true" }
    };
 }

HttpClientInstance

Gets or sets the System.Net.Http.HttpClient instance used by the SfUploader component
for performing upload and remove operations.

Declaration

public HttpClient HttpClientInstance { get; set; }

Property Value

Type	Description
System.Net.Http.HttpClient	The System.Net.Http.HttpClient instance that handles HTTP requests for the SfUploader component. If not set, the component will use the globally injected System.Net.Http.HttpClient instance from the application.

Remarks

Use this property to bind a custom System.Net.Http.HttpClient instance to the SfUploader component. This allows for centralized management of HTTP configurations such as headers, base addresses, and timeouts,
ensuring consistent HTTP settings across your application.

If HttpClientInstance is not specified, the component defaults to using the globally injected System.Net.Http.HttpClient instance provided in the application�s Program.cs or Startup.cs.

Examples

 
@inject HttpClient httpClient; 
 
 
 
 

This example demonstrates setting the HttpClientInstance property to a globally injected
System.Net.Http.HttpClient instance, enabling shared HTTP configurations within the SfUploader component.

ID

Gets the ID of the Uploader component.

Declaration

public string ID { get; set; }

Property Value

Type	Description
System.String	Accepts the string value.

InputAttributes

Gets or sets an additional input attributes such as disabled, value, and more to add the input file element.

Declaration

public Dictionary<string, object> InputAttributes { get; set; }

Property Value

Type	Description
System.Collections.Generic.Dictionary<System.String, System.Object>	A dictionary of additional input attributes for the root element of the component.

Remarks

If you configured both property and equivalent input attribute, the component considers the property value.

MaxFileSize

Gets or sets the internal storage for MaxFileSize property.

Declaration

public double MaxFileSize { get; set; }

Property Value

Type	Description
System.Double	Accepts the double value representing that the maximum file size for the component. The default value is 30000000.

Remarks

The property used to make sure that you cannot upload too large files.

MinFileSize

Gets or sets the internal storage for MinFileSize property.

Declaration

public double MinFileSize { get; set; }

Property Value

Type	Description
System.Double	A double value representing the minimum file size for the component. The default value is 0.

SequentialUpload

Gets or sets the internal storage for SequentialUpload property.

Declaration

public bool SequentialUpload { get; set; }

Property Value

Type	Description
System.Boolean	true if sequential upload is enabled; otherwise, false. The default value is false.

Remarks

When the SequentialUpload property is enabled, the file upload component uploads files one after another instead of simultaneously.

ShowFileList

Gets or sets the internal storage for ShowFileList property.

Declaration

public bool ShowFileList { get; set; }

Property Value

Type	Description
System.Boolean	true if the file list should be shown; otherwise, false. The default value is true.

Remarks

This property is used to hide the default file list and design your own template for the file list using the Template property.

ShowProgressBar

Gets or sets a value indicating whether to show the progress bar while uploading a file.

Declaration

public bool ShowProgressBar { get; set; }

Property Value

Type	Description
System.Boolean	true if the progress bar should be shown; otherwise, false. The default value is true.

Examples

@using Syncfusion.Blazor.Inputs
<SfUploader ID="UploadFiles" ShowProgressBar="false">
    <UploaderAsyncSettings SaveUrl="api/SampleData/Save" RemoveUrl="api/SampleData/Remove" />
</SfUploader>

TabIndex

Gets or sets the tab order of the component.

Declaration

public int TabIndex { get; set; }

Property Value

Type	Description
System.Int32	An integer value representing the tab index of the Uploader component. The default value is 0.

Template

Gets or sets a template that is used to customize the content of each file in the list.

Declaration

public RenderFragment<FileInfo> Template { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.RenderFragment<FileInfo>	The template content. The default value is null.

Examples

@using Syncfusion.Blazor.Inputs
@inject HttpClient Http
<SfUploader ID="UploadFiles" DropEffect="DropEffect.Copy">
    <UploaderAsyncSettings SaveUrl="api/SampleData/Save" RemoveUrl="api/SampleData/Remove"/>
    <UploaderTemplates>
        <Template Context="HttpContext">
            <div style="padding: 7px;">
                <h5 title="@(HttpContext.Name)">@(HttpContext.Name)</h5>
                <i>@(HttpContext.Size) Bytes</i>
            </div>
        </Template>
    </UploaderTemplates>
</SfUploader>

Methods

BuildRenderTree(RenderTreeBuilder)

Declaration

protected override void BuildRenderTree(RenderTreeBuilder __builder)

Parameters

Type	Name	Description
Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder	__builder

BytesToSizeAsync(Double)

Converts bytes value into kilobytes or megabytes depending on the size based on binary prefix.

Declaration

public Task<string> BytesToSizeAsync(double bytes)

Parameters

Type	Name	Description
System.Double	bytes	The file size in bytes to be converted.

Returns

Type	Description
System.Threading.Tasks.Task<System.String>	A System.Threading.Tasks.Task<> that represents the asynchronous operation. The task result contains a System.String representing the formatted file size with appropriate units (B, KB, MB, GB, etc.).

Remarks

This method converts numeric byte values to human-readable file size representations using binary prefixes (1024-based calculation). For example, 1024 bytes will be converted to "1 KB", and 1048576 bytes will be converted to "1 MB". The conversion follows the binary prefix standard where each unit is 1024 times larger than the previous unit.

Examples

Convert file size from bytes to readable format:

string fileSize = await uploaderInstance.BytesToSizeAsync(2048);
// Returns "2 KB"

CancelAsync(FileInfo[])

Stops the in-progress chunked upload based on the specified file data.

Declaration

public Task CancelAsync(FileInfo[] fileData = null)

Parameters

Type	Name	Description
FileInfo[]	fileData	An array of Syncfusion.Blazor.Inputs.SfUploader.FileInfo objects representing the files to cancel. If null, all in-progress uploads will be canceled.

Returns

Type	Description
System.Threading.Tasks.Task	A System.Threading.Tasks.Task that represents the asynchronous cancel operation.

Remarks

When the file upload is canceled using this method, the partially uploaded file chunks are automatically removed from the server. This method is particularly useful for chunked uploads where large files are divided into smaller parts for transmission. If no specific file data is provided, all currently uploading files will be canceled.

Examples

Cancel specific files or all uploads:

// Cancel specific files
await uploaderInstance.CancelAsync(selectedFiles);

// Cancel all uploads
await uploaderInstance.CancelAsync();

ClearAllAsync()

Clears all file entries from the upload list, including both uploaded files and files in the upload queue.

Declaration

public Task ClearAllAsync()

Returns

Type	Description
System.Threading.Tasks.Task	A System.Threading.Tasks.Task that represents the asynchronous clear operation.

Remarks

This method removes all files from the uploader component, whether they are already uploaded, currently uploading, or waiting in the queue. The method behavior varies based on whether the uploader is configured with server-side processing (SaveUrl) or client-side only processing. For server-side uploads, it communicates with the server to clear files, while for client-side only uploads, it clears the local file list.

Examples

Clear all files from the uploader:

await uploaderInstance.ClearAllAsync();

GetFileDetails(List<FileInfo>)

Retrieves and processes detailed information for the specified files. This method is invoked from JavaScript interop.

Declaration

public Task GetFileDetails(List<FileInfo> file)

Parameters

Type	Name	Description
System.Collections.Generic.List<FileInfo>	file	A System.Collections.Generic.List<> of Syncfusion.Blazor.Inputs.SfUploader.FileInfo objects containing the files for which details need to be retrieved.

Returns

Type	Description
System.Threading.Tasks.Task	A System.Threading.Tasks.Task that represents the asynchronous file details retrieval operation.

GetFilesDataAsync(Nullable<Double>)

Retrieves the data of files that are displayed in the file list.

Declaration

public Task<List<FileInfo>> GetFilesDataAsync(Nullable<double> index = null)

Parameters

Type	Name	Description
System.Nullable<System.Double>	index	The optional index of a specific file to retrieve. If null, all files in the list are returned.

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.List<FileInfo>>	A System.Threading.Tasks.Task<> that represents the asynchronous operation. The task result contains a System.Collections.Generic.List<> of Syncfusion.Blazor.Inputs.SfUploader.FileInfo objects representing the file data.

Remarks

This method returns information about files currently displayed in the uploader's file list. If an index is specified, only the file at that position is returned (wrapped in a list). If no index is provided, all files in the current file list are returned. The behavior differs between server-side and client-side configurations, with server-side calls communicating with JavaScript interop.

Examples

Get all files or a specific file by index:

// Get all files
List<FileInfo> allFiles = await uploaderInstance.GetFilesDataAsync();

// Get specific file by index
List<FileInfo> specificFile = await uploaderInstance.GetFilesDataAsync(0);

PauseAsync(List<FileInfo>, Nullable<Boolean>)

Pauses the in-progress chunked upload based on the specified file data.

Declaration

public Task PauseAsync(List<FileInfo> fileData = null, Nullable<bool> custom = null)

Parameters

Type	Name	Description
System.Collections.Generic.List<FileInfo>	fileData	A System.Collections.Generic.List<> of Syncfusion.Blazor.Inputs.SfUploader.FileInfo objects representing the files to pause. If null, all in-progress uploads will be paused.
System.Nullable<System.Boolean>	custom	A System.Boolean value indicating whether custom UI is being used. Set to true if using custom UI templates.

Returns

Type	Description
System.Threading.Tasks.Task	A System.Threading.Tasks.Task that represents the asynchronous pause operation.

Remarks

This method temporarily halts the upload process for chunked file uploads, allowing them to be resumed later using ResumeAsync(FileInfo[], Nullable<Boolean>). Pausing is particularly useful for large file uploads where users might want to temporarily stop the upload process due to network conditions or other priorities. The paused uploads maintain their current progress and can be resumed from the same point without losing uploaded chunks.

Examples

Pause specific files or all uploads:

// Pause specific files
await uploaderInstance.PauseAsync(selectedFiles);

// Pause all uploads
await uploaderInstance.PauseAsync();

RemoveAsync(FileInfo[], Nullable<Boolean>, Nullable<Boolean>, Nullable<Boolean>, Object)

Removes the uploaded files from the server manually by calling the remove URL action.

Declaration

public Task RemoveAsync(FileInfo[] fileData = null, Nullable<bool> customTemplate = null, Nullable<bool> removeDirectly = null, Nullable<bool> postRawFile = null, object args = null)

Parameters

Type	Name	Description
FileInfo[]	fileData	An array of Syncfusion.Blazor.Inputs.SfUploader.FileInfo objects representing the files to remove from the file list and server. If null or empty, the complete file list will be cleared.
System.Nullable<System.Boolean>	customTemplate	A System.Boolean value indicating whether the component is rendering with a custom template. Set to true if using custom templates.
System.Nullable<System.Boolean>	removeDirectly	A System.Boolean value indicating whether to remove files directly without triggering removing events. Set to true to bypass event handling.
System.Nullable<System.Boolean>	postRawFile	A System.Boolean value indicating the data format to post to the remove action. Set to false to post only the file name instead of the complete file data.
System.Object	args	Additional arguments to pass to the remove action.

Returns

Type	Description
System.Threading.Tasks.Task	A System.Threading.Tasks.Task that represents the asynchronous remove operation.

Remarks

This method removes files both from the client-side file list and from the server storage by calling the configured remove URL. If no specific file data is provided, all files in the current list will be removed. The method behavior varies based on whether server-side processing is configured through the SaveUrl property. For client-side only configurations, files are removed from the local file collection without server communication.

Examples

Remove specific files or clear all files:

// Remove specific files
await uploaderInstance.RemoveAsync(selectedFiles);

// Clear all files
await uploaderInstance.RemoveAsync();

// Remove files with custom options
await uploaderInstance.RemoveAsync(selectedFiles, customTemplate: true, removeDirectly: false);

ResumeAsync(FileInfo[], Nullable<Boolean>)

Resumes the chunked upload that was previously paused based on the specified file data.

Declaration

public Task ResumeAsync(FileInfo[] fileData = null, Nullable<bool> custom = null)

Parameters

Type	Name	Description
FileInfo[]	fileData	An array of Syncfusion.Blazor.Inputs.SfUploader.FileInfo objects representing the files to resume. If null, all paused uploads will be resumed.
System.Nullable<System.Boolean>	custom	A System.Boolean value indicating whether custom UI is being used. Set to true if using custom UI templates.

Returns

Type	Description
System.Threading.Tasks.Task	A System.Threading.Tasks.Task that represents the asynchronous resume operation.

Remarks

This method continues the upload process for files that were previously paused using PauseAsync(List<FileInfo>, Nullable<Boolean>). The upload resumes from the exact point where it was paused, utilizing the already uploaded chunks without re-uploading them. This feature is particularly useful for handling large file uploads where network interruptions or user preferences require temporary pausing.

Examples

Resume specific paused files or all paused uploads:

// Resume specific files
await uploaderInstance.ResumeAsync(pausedFiles);

// Resume all paused uploads
await uploaderInstance.ResumeAsync();

RetryAsync(FileInfo[], Nullable<Boolean>, Nullable<Boolean>)

Retries the canceled or failed file upload based on the specified file data.

Declaration

public Task RetryAsync(FileInfo[] fileData = null, Nullable<bool> fromcanceledStage = null, Nullable<bool> custom = null)

Parameters

Type	Name	Description
FileInfo[]	fileData	An array of Syncfusion.Blazor.Inputs.SfUploader.FileInfo objects representing the files to retry. If null, all canceled or failed uploads will be retried.
System.Nullable<System.Boolean>	fromcanceledStage	A System.Boolean value indicating the retry starting point. Set to true to retry from the canceled stage, or false to retry from the initial stage.
System.Nullable<System.Boolean>	custom	A System.Boolean value indicating whether custom UI is being used. Set to true if using custom UI templates.

Returns

Type	Description
System.Threading.Tasks.Task	A System.Threading.Tasks.Task that represents the asynchronous retry operation.

Remarks

This method allows users to restart uploads for files that have failed or been canceled during the upload process. When retrying from the canceled stage, the upload continues from where it was interrupted, preserving any successfully uploaded chunks. When retrying from the initial stage, the entire upload process starts over from the beginning. This functionality is essential for handling network issues, server timeouts, or user-initiated cancellations.

Examples

Retry failed uploads with different options:

// Retry specific files from canceled stage
await uploaderInstance.RetryAsync(failedFiles, fromcanceledStage: true);

// Retry all failed files from initial stage
await uploaderInstance.RetryAsync(fromcanceledStage: false);

SortFileListAsync(FileInfo[])

Sorts the file data alphabetically based on the file names.

Declaration

public Task<List<FileInfo>> SortFileListAsync(FileInfo[] filesData = null)

Parameters

Type	Name	Description
FileInfo[]	filesData	An array of Syncfusion.Blazor.Inputs.SfUploader.FileInfo objects representing the files to sort. If null, all files in the current list will be sorted.

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.List<FileInfo>>	A System.Threading.Tasks.Task<> that represents the asynchronous operation. The task result contains a System.Collections.Generic.List<> of Syncfusion.Blazor.Inputs.SfUploader.FileInfo objects sorted alphabetically by file name.

Remarks

This method organizes the file list in alphabetical order based on the file names, making it easier for users to locate specific files. The sorting is case-insensitive and follows standard alphabetical ordering rules. If no specific file data is provided, the method will sort all files currently present in the uploader's file list.

Examples

Sort files alphabetically:

// Sort specific files
List<FileInfo> sortedFiles = await uploaderInstance.SortFileListAsync(selectedFiles);

// Sort all files in the list
List<FileInfo> allSortedFiles = await uploaderInstance.SortFileListAsync();

UploadAsync(FileInfo[], Nullable<Boolean>)

Initiates the upload process manually by calling the save URL action.

Declaration

public Task UploadAsync(FileInfo[] files = null, Nullable<bool> custom = null)

Parameters

Type	Name	Description
FileInfo[]	files	An array of Syncfusion.Blazor.Inputs.SfUploader.FileInfo objects representing the specific files to upload. If null, all files in the upload queue will be processed.
System.Nullable<System.Boolean>	custom	A System.Boolean value indicating whether to use custom file handling. Set to true for custom file processing.

Returns

Type	Description
System.Threading.Tasks.Task	A System.Threading.Tasks.Task that represents the asynchronous upload operation.

Remarks

This method manually triggers the upload process for files in the uploader component. If no specific files are provided, all files currently in the upload queue will be uploaded. The method behavior varies based on the uploader configuration: for server-side uploads, it communicates with the configured SaveUrl, while for client-side only scenarios, it processes files locally through the upload handler. This method is useful when you need programmatic control over when uploads should begin.

Examples

Upload files manually:

// Upload specific files
await uploaderInstance.UploadAsync(selectedFiles);

// Upload all queued files
await uploaderInstance.UploadAsync();

// Upload with custom handling
await uploaderInstance.UploadAsync(selectedFiles, custom: true);