Class UploaderModel

Defines the comprehensive configuration model for the Syncfusion Blazor Uploader component.

Inheritance

System.Object

UploaderModel

Namespace: Syncfusion.Blazor.Inputs

Assembly: Syncfusion.Blazor.dll

Syntax

public class UploaderModel : Object

Remarks

This class serves as the primary configuration model for the uploader component, containing all properties and event handlers that control the behavior, appearance, and functionality of the file upload component. It provides comprehensive options for customizing upload behavior, validation, styling, and user interaction patterns, enabling developers to create robust file upload solutions tailored to their specific requirements.

Examples

The following example demonstrates basic configuration of the uploader component:

<SfUploader AutoUpload="true" 
            AllowedExtensions=".jpg,.png,.pdf"
            MaxFileSize="10485760"
            Multiple="true">
    <UploaderAsyncSettings SaveUrl="/api/upload" RemoveUrl="/api/remove" />
    <UploaderEvents BeforeUpload="OnBeforeUpload" Success="OnUploadSuccess" />
</SfUploader>

Constructors

UploaderModel()

Declaration

public UploaderModel()

Properties

ActionComplete

Gets or sets the event callback that is triggered after all selected files have been processed for upload.

Declaration

public EventCallback<object> ActionComplete { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when all upload operations are completed, regardless of success or failure.

Remarks

This event is triggered after all selected files have completed their upload process, whether they succeeded or failed. It provides a comprehensive overview of the batch upload operation and is useful for implementing post-upload cleanup, user notifications, or summary reporting functionality.

AllowedExtensions

Gets or sets the file extensions allowed for upload in the uploader component.

Declaration

public string AllowedExtensions { get; set; }

Property Value

Type	Description
System.String	A string containing comma-separated file extensions (e.g., ".jpg,.png,.pdf"), or an empty string to allow all file types.

Remarks

This property restricts the types of files that users can select and upload. Extensions should be specified with a leading dot and separated by commas. For example, to allow only image files, set this property to ".jpg,.jpeg,.png,.gif". When this property is set, the file selection dialog will filter available files to show only those with matching extensions, and validation will prevent upload of non-matching file types.

Examples

To allow only image files: AllowedExtensions = ".jpg,.png,.gif"

AsyncSettings

Gets or sets the asynchronous upload settings for server-side file operations.

Declaration

public UploaderAsyncSettings AsyncSettings { get; set; }

Property Value

Type	Description
UploaderAsyncSettings	An UploaderAsyncSettings object containing save and remove URLs and other async configurations, or null to disable asynchronous operations.

Remarks

This property configures the server endpoints for save and remove operations, enabling asynchronous file upload functionality. It specifies the URLs that handle file upload and removal on the server side, along with additional settings like chunk size, retry behavior, and delay configurations. When properly configured, this allows for automatic file upload with progress tracking and error handling.

AutoUpload

Gets or sets a value indicating whether files should be automatically uploaded when added to the upload queue.

Declaration

public bool AutoUpload { get; set; }

Property Value

Type	Description
System.Boolean	true to automatically upload files when they are selected; otherwise, false. The default is true.

Remarks

When set to true, files are automatically uploaded as soon as they are selected or dropped. When set to false, files are added to the upload queue but require manual initiation of the upload process through the upload button. Setting this to false also displays upload and clear buttons in the file list, giving users complete control over when uploads occur.

BeforeRemove

Gets or sets the event callback that is triggered before files are removed from the server.

Declaration

public EventCallback<object> BeforeRemove { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked before file removal operations to allow confirmation or cancellation.

Remarks

This event is triggered when users attempt to remove uploaded files from the server. It provides an opportunity to implement confirmation dialogs, validate removal permissions, or cancel the removal operation based on business logic requirements.

BeforeUpload

Gets or sets the event callback that is triggered before the upload process begins.

Declaration

public EventCallback<object> BeforeUpload { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked before upload operations start, allowing request customization.

Remarks

This event is triggered before the file upload process begins and is commonly used to add additional parameters to the upload request, such as authentication tokens, metadata, or custom headers required by the server-side upload handler.

Buttons

Gets or sets the custom button text and content for the uploader interface.

Declaration

public UploaderButtons Buttons { get; set; }

Property Value

Type	Description
UploaderButtons	An UploaderButtons object containing custom button configurations, or null to use default button text.

Remarks

This property allows comprehensive customization of the text displayed on the browse, upload, and clear buttons. The button text can be plain text or HTML content for enhanced visual design. If both this property and localization are configured, this property takes precedence over localized text, enabling fine-grained control over button appearance and content.

Canceling

Gets or sets the event callback that is triggered when chunk file upload operations are canceled.

Declaration

public EventCallback<object> Canceling { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when chunk-based upload operations are canceled.

Remarks

This event is triggered specifically when chunk-based file upload operations are canceled by the user or system. It provides information about the cancellation context and allows for cleanup operations or user feedback regarding the canceled upload.

Change

Gets or sets the upload change event arguments when files are selected or dropped.

Declaration

public UploadChangeEventArgs Change { get; set; }

Property Value

Type	Description
UploadChangeEventArgs	An UploadChangeEventArgs object containing information about file changes, or null if no changes have occurred.

Remarks

This property contains the event arguments for file selection and drop operations. It provides access to the list of files that have been selected or dropped, enabling custom handling of file changes and immediate access to uploaded file data.

ChunkFailure

Gets or sets the failure event arguments when chunk file uploads fail.

Declaration

public FailureEventArgs ChunkFailure { get; set; }

Property Value

Type	Description
FailureEventArgs	A FailureEventArgs object containing failure information, or null if no failures have occurred.

Remarks

This property contains the event arguments for chunk upload failures. It provides detailed information about failed chunk operations, including retry options and error context, enabling robust error handling in chunk-based upload scenarios.

ChunkSuccess

Gets or sets the success event arguments when chunk files are uploaded successfully.

Declaration

public SuccessEventArgs ChunkSuccess { get; set; }

Property Value

Type	Description
SuccessEventArgs	A SuccessEventArgs object containing success information, or null if no successful operations have occurred.

Remarks

This property contains the event arguments for successful chunk upload operations. It provides detailed information about completed chunk uploads, including server responses and progress information, enabling precise tracking of chunk-based upload progress.

ChunkUploading

Gets or sets the event callback that is triggered when chunk upload processes start.

Declaration

public EventCallback<object> ChunkUploading { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when individual chunk upload operations begin.

Remarks

This event is triggered for each chunk upload operation when chunk-based uploading is enabled. It is commonly used to add additional parameters to chunk upload requests or implement chunk-specific customization logic for large file uploads.

Clearing

Gets or sets the event callback that is triggered before clearing the file list.

Declaration

public EventCallback<object> Clearing { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked before the file list is cleared.

Remarks

This event is triggered when users click the "clear" button to remove all files from the upload queue. It provides an opportunity to implement confirmation dialogs or cancel the clear operation based on user preferences or application requirements.

Created

Gets or sets the event callback that is triggered when the uploader component is created.

Declaration

public EventCallback<object> Created { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when the uploader component initialization is complete.

Remarks

This event is triggered when the uploader component has finished its initialization process. It provides an opportunity to perform additional setup, apply custom configurations, or initialize related functionality that depends on the uploader being fully ready.

CssClass

Gets or sets the CSS class names to be applied to the uploader component.

Declaration

public string CssClass { get; set; }

Property Value

Type	Description
System.String	A string containing one or more CSS class names separated by spaces, or an empty string for no custom classes.

Remarks

This property allows comprehensive custom styling of the uploader component by applying CSS classes to the root element. Multiple classes can be specified by separating them with spaces. These classes enable complete customization of the component's appearance, layout, and behavior through CSS styling, including themes, responsive designs, and custom branding requirements.

DirectoryUpload

Gets or sets a value indicating whether folder upload functionality is enabled for the uploader component.

Declaration

public bool DirectoryUpload { get; set; }

Property Value

Type	Description
System.Boolean	true to enable folder upload functionality; otherwise, false. The default is false.

Remarks

When enabled, users can select and upload entire folders rather than just individual files. This feature allows for bulk upload of folder contents while preserving the original folder structure. Note that folder upload support depends on browser capabilities and may not be available in all browsers or older browser versions.

DropArea

Gets or sets the target element or selector for drag-and-drop file upload operations.

Declaration

public object DropArea { get; set; }

Property Value

Type	Description
System.Object	An object specifying the drop target element or CSS selector, or null to use the default drop area.

Remarks

This property allows customization of the drag-and-drop target area beyond the default uploader interface. By default, the uploader creates a wrapper around the file input that serves as the drop target. Setting this property allows specification of a different element as the drop zone, enabling more flexible UI designs and integration with custom layouts or existing page elements.

DropEffect

Gets or sets the visual effect displayed during drag-and-drop operations.

Declaration

public DropEffect DropEffect { get; set; }

Property Value

Type	Description
DropEffect	A DropEffect enumeration value specifying the drag operation effect. The default is Default.

Remarks

This property controls the visual feedback shown to users during drag-and-drop operations, providing clear indication of the intended action. The available effects are:

• Copy - Indicates that the dragged files will be copied to the target location
• Move - Indicates that the dragged files will be moved to the target location
• Link - Indicates that a link or reference to the files will be created
• None - No visual effect is displayed during drag operations
• Default - Uses the browser's default drag effect based on the context

Enabled

Gets or sets a value indicating whether the uploader component allows user interaction.

Declaration

public bool Enabled { get; set; }

Property Value

Type	Description
System.Boolean	true if the uploader is enabled for user interaction; otherwise, false. The default is true.

Remarks

When set to false, the uploader component becomes disabled and users cannot interact with it. This includes file selection, drag-and-drop operations, and button clicks. Disabled uploader components typically appear grayed out and do not respond to user input, making them suitable for scenarios where upload functionality should be temporarily unavailable.

EnablePersistence

Gets or sets a value indicating whether to persist the uploader state between page reloads.

Declaration

public bool EnablePersistence { get; set; }

Property Value

Type	Description
System.Boolean	true to enable state persistence; otherwise, false. The default is false.

Remarks

When enabled, the uploader component will persist its state (including the Files collection) between page reloads, providing continuity of the upload experience even if the page is refreshed or navigated away from and back. This feature is particularly useful in single-page applications or scenarios where users might accidentally reload the page during upload operations.

EnableRtl

Gets or sets a value indicating whether to render the uploader component in right-to-left (RTL) direction.

Declaration

public bool EnableRtl { get; set; }

Property Value

Type	Description
System.Boolean	true to enable RTL rendering; otherwise, false. The default is false.

Remarks

When enabled, the uploader component will render with right-to-left text direction and layout, which is essential for languages such as Arabic, Hebrew, and other RTL languages. This affects both text alignment and the overall component layout direction, ensuring proper display and usability in RTL language contexts.

Failure

Gets or sets the failure event arguments when AJAX requests fail during upload or removal operations.

Declaration

public FailureEventArgs Failure { get; set; }

Property Value

Type	Description
FailureEventArgs	A FailureEventArgs object containing failure information, or null if no failures have occurred.

Remarks

This property contains the event arguments for general upload or removal failures. It provides comprehensive information about failed operations, including error details and retry options, enabling robust error handling and user feedback in upload scenarios.

FileListRendering

Gets or sets the event callback that is triggered before rendering each file item in the file list.

Declaration

public EventCallback<object> FileListRendering { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked for each file item during file list rendering.

Remarks

This event is triggered before each file item is rendered in the file list, providing an opportunity to customize the structure and appearance of individual file items. It enables implementation of custom file item templates and dynamic styling based on file properties.

Files

Gets or sets the list of files that will be preloaded when the uploader component is rendered.

Declaration

public List<UploaderUploadedFiles> Files { get; set; }

Property Value

Type	Description
System.Collections.Generic.List<UploaderUploadedFiles>	A System.Collections.Generic.List<> containing the preloaded file configurations, or null if no files are preloaded.

Remarks

This property is used to display and manage files that have already been uploaded to the server. By default, preloaded files are configured with an "uploaded successfully" state. The following properties are mandatory for each preloaded file configuration:

• Name - The file name including extension
• Size - The file size in bytes
• Type - The MIME type of the file

This feature enables seamless integration with existing file management systems where files may have been uploaded in previous sessions or through other means.

HtmlAttributes

Gets or sets additional HTML attributes to be applied to the root element of the uploader component.

Declaration

public object HtmlAttributes { get; set; }

Property Value

Type	Description
System.Object	An object containing HTML attributes as key-value pairs, or null if no additional attributes are specified.

Remarks

This property allows addition of custom HTML attributes such as styles, classes, data attributes, and more to the uploader's root element. If both this property and equivalent component-specific properties are configured (such as CssClass), the component-specific property values take precedence over the HTML attributes, ensuring predictable behavior and component integrity.

Locale

Gets or sets the global culture and localization setting for the uploader component.

Declaration

public string Locale { get; set; }

Property Value

Type	Description
System.String	A string representing the locale identifier (e.g., "en-US", "fr-FR"), or an empty string to use the default locale.

Remarks

This property specifies the culture and localization context for the uploader component, affecting the display language of built-in text, date formats, number formats, and other culture-sensitive elements. The locale setting influences button text, error messages, and other user-facing content, enabling proper internationalization support for global applications.

MaxFileSize

Gets or sets the maximum allowed file size for uploads in bytes.

Declaration

public double MaxFileSize { get; set; }

Property Value

Type	Description
System.Double	A double value representing the maximum file size in bytes. The default value is 30,000,000 bytes (approximately 30 MB).

Remarks

This property enforces a maximum file size limit to prevent users from uploading excessively large files that could impact server performance, storage capacity, or network bandwidth. Files exceeding this size limit will be rejected with appropriate validation messages, helping maintain system stability and reasonable resource usage across upload operations.

MinFileSize

Gets or sets the minimum required file size for uploads in bytes.

Declaration

public double MinFileSize { get; set; }

Property Value

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

Remarks

This property enforces a minimum file size requirement to prevent users from uploading empty files or files that are too small to contain meaningful content. This validation helps ensure data quality and prevents accidental upload of corrupted or incomplete files that could cause issues in downstream processing or storage systems.

Multiple

Gets or sets a value indicating whether multiple files can be selected and uploaded simultaneously.

Declaration

public bool Multiple { get; set; }

Property Value

Type	Description
System.Boolean	true to allow selection and upload of multiple files; otherwise, false. The default is true.

Remarks

When set to true, users can select multiple files at once through the file selection dialog or drag-and-drop multiple files simultaneously. When set to false, the uploader restricts selection to a single file at a time, which is suitable for scenarios where only one file should be processed or uploaded per operation.

Pausing

Gets or sets the event callback that is triggered when chunk file uploads are paused.

Declaration

public EventCallback<object> Pausing { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when chunk upload operations are paused.

Remarks

This event is triggered when chunk-based file upload operations are paused by user action or system conditions. It provides context about the pause operation and enables implementation of custom pause handling or user feedback functionality.

Progress

Gets or sets the progress event arguments during file upload operations.

Declaration

public ProgressEventArgs Progress { get; set; }

Property Value

Type	Description
ProgressEventArgs	A ProgressEventArgs object containing progress information, or null if no progress events have occurred.

Remarks

This property contains the event arguments for upload progress updates. It provides real-time information about upload progress, including bytes transferred and completion percentages, enabling implementation of progress indicators and user feedback during file transfers.

Removing

Gets or sets the event callback that is triggered when files are being removed.

Declaration

public EventCallback<object> Removing { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked during file removal operations.

Remarks

This event is triggered during the file removal process and provides an opportunity to implement confirmation dialogs, validate removal permissions, or perform cleanup operations before files are actually removed from the server.

Resuming

Gets or sets the event callback that is triggered when paused chunk file uploads are resumed.

Declaration

public EventCallback<object> Resuming { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when paused chunk upload operations are resumed.

Remarks

This event is triggered when previously paused chunk-based upload operations are resumed. It provides context about the resume operation and enables implementation of custom resume handling or progress tracking functionality for interrupted uploads.

Selected

Gets or sets the event callback that is triggered after files are selected or dropped.

Declaration

public EventCallback<object> Selected { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when files are selected or dropped for upload.

Remarks

This event is triggered after files are selected or dropped, providing an opportunity to validate file selections, modify the file list, or implement custom selection handling before files are added to the upload queue.

SequentialUpload

Gets or sets a value indicating whether files should be uploaded sequentially rather than simultaneously.

Declaration

public bool SequentialUpload { get; set; }

Property Value

Type	Description
System.Boolean	true to enable sequential upload processing; otherwise, false for simultaneous uploads. The default is false.

Remarks

By default, the uploader component processes multiple files simultaneously for optimal performance. When this property is enabled, the component performs uploads one after another in sequence, which can be beneficial for scenarios with limited bandwidth, server constraints, or when upload order is important for business logic or processing requirements.

ShowFileList

Gets or sets a value indicating whether the default file list should be rendered.

Declaration

public bool ShowFileList { get; set; }

Property Value

Type	Description
System.Boolean	true to show the default file list; otherwise, false to hide it. The default is true.

Remarks

When set to true, the component displays the built-in file list showing selected files with their details, progress, and status information. When set to false, the default file list is hidden, allowing developers to create completely custom file list implementations using templates or external components while still leveraging the uploader's core functionality.

Success

Gets or sets the success event arguments when AJAX requests succeed during upload or removal operations.

Declaration

public SuccessEventArgs Success { get; set; }

Property Value

Type	Description
SuccessEventArgs	A SuccessEventArgs object containing success information, or null if no successful operations have occurred.

Remarks

This property contains the event arguments for successful upload or removal operations. It provides comprehensive information about completed operations, including server responses and operation details, enabling implementation of success handling and user feedback functionality.

Template

Gets or sets the HTML template string used to customize the content of each file item in the list.

Declaration

public string Template { get; set; }

Property Value

Type	Description
System.String	A string containing HTML template markup for file list items, or null to use the default template.

Remarks

This property allows complete customization of how individual files are displayed in the file list. The template can include HTML markup, CSS classes, and data binding expressions to create rich, interactive file list items that match application design requirements. When specified, this template overrides the default file list item rendering, providing maximum flexibility in file list presentation.

Uploading

Gets or sets the event callback that is triggered when upload processes start.

Declaration

public EventCallback<object> Uploading { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when upload operations begin.

Remarks

This event is triggered when the file upload process starts and is commonly used to add additional parameters to upload requests, implement authentication, or perform pre-upload validation and setup operations.