FileUpload JAVASCRIPT UI Component API

FileUpload Javascript API

Class

FileUpload

FileUpload

FileUpload provides an easy and integrated way for users to upload multiple files.

Selector

smart-file-upload

Properties

AacceptDefines the file types that are allowed for upload by specifying accepted MIME types or file extensions. This property maps directly to the HTML accept attribute on the hidden file input element, which determines which files users can select in the file dialog. These files are then uploaded to the server endpoint specified in the uploadUrl property. Setting this property ensures that only files matching the specified types can be chosen and submitted.
AanimationSpecifies or retrieves the current animation mode. When set to 'none', all animations are disabled and transitions will not be applied. Use this property to control whether animations are enabled or disabled within the component or element.
AappendToAppends the selected files list to a custom container specified by the user. If the property value is a string, it must correspond to the ID of an existing HTML element in the DOM. This element will serve as the new container where the uploaded files list will be rendered. If the provided ID does not match any element in the DOM, the operation will not proceed. This allows developers to control exactly where the files list appears in the application's interface.
AautoUploadDetermines whether files are automatically uploaded immediately after they are selected by the user. When set to true, the upload process begins as soon as files are chosen; when false, uploading must be triggered manually.
DdirectoryEnables users to upload an entire directory at once, including all files contained within any nested subfolders. When this option is selected, the upload process will automatically include every file from the selected directory and its subdirectories. Note: This feature is currently supported only in Firefox and Chrome browsers.
DdisabledControls whether the element is interactive or not. When enabled, the element can be interacted with by the user; when disabled, the element appears inactive and does not respond to user input.
DdropZoneSpecifies a custom container element to serve as the drop zone for file uploads. When files are dropped onto this container, they will be added to the fileUpload component’s file list. If the 'dropZone' property is set to true, the component will use its internal default drop zone. If 'dropZone' is assigned the ID of an existing HTML element in the DOM, that particular element will be used as the drop zone area for file uploads instead. This allows for flexible placement and styling of the drop zone within your application.
HhideFooterConceals the entire footer section, including all of its contents—specifically the "Upload All," "Pause All," and "Close All" buttons—preventing users from accessing these actions.
IitemTemplateEnhances the file item display by applying a custom template to each item in the uploaded files list. This allows you to define the appearance and layout of uploaded file entries, enabling features such as displaying file names, sizes, icons, previews, or custom actions within each file item.
UunlockKeyDefines the unlockKey property, which is used to retrieve or assign the unique key required to unlock access to the product. Setting this key grants authorization for product usage, while getting it returns the current unlock key in use.
LlocaleSpecifies or retrieves the current language setting for displaying messages. This property works together with the messages property to select the appropriate set of localized text based on the chosen language code (e.g., "en", "fr", "es"). Use this property to dynamically change or access the language used in your application's user interface.
LlocalizeFormatFunctionA callback function that allows you to customize the format of messages returned by the Localization Module. Use this to modify how localized messages are structured or displayed before they are delivered to your application.
MmessagesConfigures the text labels displayed in the widget interface, enabling support for localization and customization of user-facing messages. The localization object should contain the following fields: browse, pauseFile, cancelFile, uploadFile, pauseAll, cancelAll, and uploadAll—each representing the corresponding action's text label. For optimal results and proper display, set these localization messages before the widget element is initialized.
MmultipleSpecifies or retrieves whether users are permitted to select and upload multiple items simultaneously. When enabled, users can choose more than one file or item within the upload interface.
NnameGets or sets the name attribute of the hidden file input element. This name is used as the key in the form data when files are uploaded to the server via the URL specified in the uploadUrl property.
RreadonlyWhen an element is set to readonly, users can view its content but cannot modify or edit it. However, unlike disabled elements, readonly elements remain focusable and their content can typically still be selected and copied. This property is commonly applied to input fields and textareas to prevent changes while allowing visibility and text selection.
RresponseHandlerA callback function designed to process server responses, allowing you to handle successful results as well as different error codes and statuses returned from the server. This enables customized handling of success, failure, and edge-case scenarios based on the server’s response.
RrightToLeftSets or retrieves a value that determines whether the element's alignment supports right-to-left (RTL) text direction, which is commonly used for languages such as Arabic or Hebrew. When enabled, the element and its content are visually aligned to accommodate RTL locales, ensuring proper display and user interface behavior for RTL language users.
SsetHeadersA callback function that allows you to modify or set custom headers for the XMLHttpRequest (XHR) used during the file upload process. This function receives the XHR object as a parameter, enabling you to add, update, or remove HTTP headers before the request is sent.
SshowProgressDisplays a visual progress bar at the bottom of each item being uploaded, providing real-time feedback on the upload status. The progress bar dynamically updates to reflect the current percentage of the upload completed for each individual item, allowing users to easily track the progress of their uploads.
TthemeSpecifies the theme to be applied to the element. The selected theme controls the visual appearance—including colors, fonts, and overall style—ensuring that the element’s look is consistent with the desired design scheme.
UuploadUrlSpecifies or retrieves the URL endpoint to which files will be uploaded. This property directly maps to the action attribute of the upload form. For instance, the uploadUrl property can be set to the path of a server-side script, such as a PHP, Node.js, or ASP.NET file, responsible for processing and handling the file upload operation on the server. Use this property to define where uploaded files should be sent for server-side handling.
UunfocusableIf set to true, the element is not focusable and cannot receive keyboard or programmatic focus.
RremoveUrlSets or retrieves the URL endpoint used for the remove operation. This property corresponds to the form's action attribute and determines where the form data is submitted when a remove action is triggered. For example, the removeUrl property can be set to the path of a server-side script, such as a PHP file, which processes and handles the remove request on the backend.
VvalueRetrieves the value of the uploaded file, such as the file’s name, path, size, or content, depending on the context and configuration of the file upload input. This function allows access to the selected file’s details for further processing, validation, or storage.
VvalidateFileCallback invoked immediately after files are selected to perform validation. Should return a boolean value: if true, the file is accepted; if false, the file is removed from the selection list and a 'validationError' event is triggered.

Events

FfileSelectedThis event is triggered whenever a user selects a file, such as through a file input element. It occurs immediately after the file selection is made and can be used to handle or validate the chosen file(s) before further processing, such as uploading or previewing them.
UuploadCanceledThis event is triggered when a user actively cancels an ongoing file upload process. It indicates that the file transfer has been intentionally terminated before completion, either by user action or programmatic intervention.
UuploadCompletedThis event is triggered when a file upload process has finished, indicating that the file has been successfully transmitted to the server or the upload has reached its final state (either success or failure). It can be used to execute follow-up actions, such as displaying a confirmation message, updating the user interface, or processing the uploaded file, once the upload operation is complete.
UuploadErrorThis event is triggered if an error occurs during the file upload process, causing the upload to fail. It provides information about the failure, allowing you to implement custom error handling or user notifications when a file cannot be successfully uploaded.
UuploadPausedThis event is triggered when an ongoing file upload process is temporarily halted by the user or application. It indicates that the upload is not complete and may be resumed or canceled at a later time. Event listeners can use this event to update the user interface, save upload progress, or handle other logic related to the paused upload state.
UuploadStartedThis event is triggered when a file upload process initiates, signaling that the uploading of one or more files has begun. It can be used to perform preparatory actions such as updating the user interface, initializing progress indicators, or logging the start of the file transfer.
VvalidationErrorThis event is triggered when the user-defined 'validateFile' callback function returns a failure result, indicating that the provided file did not meet the specified validation criteria.

Methods

BbrowseDisplays a popup dialog that allows the user to browse their local device and select a file to upload or process.
CcancelAllCancels all currently selected files. This action removes the files from the selection list and ensures that they are not uploaded. Any ongoing or pending uploads for these files are also stopped, preventing them from being transferred to the server.
CcancelFileCancels the specified file's upload process. This action immediately removes the file from the file list and prevents it from being uploaded or processed any further.
PpauseAllPauses the upload process for all files, temporarily halting any active uploads. While uploads are paused and new uploads cannot be started, the files themselves remain visible and accessible in the file list. No files are removed or lost during this pause; uploading can be resumed at a later time.
PpauseFilePauses the upload process for the file at the specified index. The upload for this file is temporarily suspended, preventing any data transfer, but the file itself remains listed in the upload queue. This allows for the upload to be resumed or managed at a later time without removing the file from the list.
UuploadAllUploads every file selected by the user to the server. Handles multiple files simultaneously and ensures each file is processed for upload.
UuploadFileAllows the user to select a file from their local device and upload it to the server for processing or storage.

Properties

acceptstring | null

Defines the file types that are allowed for upload by specifying accepted MIME types or file extensions. This property maps directly to the HTML accept attribute on the hidden file input element, which determines which files users can select in the file dialog. These files are then uploaded to the server endpoint specified in the uploadUrl property. Setting this property ensures that only files matching the specified types can be chosen and submitted.

Try a demo showcasing the accept property.

Example

Set the accept property. 

 <smart-file-upload accept='.img'></smart-file-upload>

Set the accept property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.accept = '.pdf';

Get the accept property. 

 const fileupload = document.querySelector('smart-file-upload');
 let accept = fileupload.accept;

animation"none" | "simple" | "advanced"

Specifies or retrieves the current animation mode. When set to 'none', all animations are disabled and transitions will not be applied. Use this property to control whether animations are enabled or disabled within the component or element.

Allowed Values

  • "none" - animation is disabled
  • "simple" - ripple animation is disabled
  • "advanced" - all animations are enabled

Default value

"advanced"

Example

Set the animation property. 

 <smart-file-upload animation='none'></smart-file-upload>

Set the animation property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.animation = 'simple';

Get the animation property. 

 const fileupload = document.querySelector('smart-file-upload');
 let animation = fileupload.animation;

appendTostring

Appends the selected files list to a custom container specified by the user. If the property value is a string, it must correspond to the ID of an existing HTML element in the DOM. This element will serve as the new container where the uploaded files list will be rendered. If the provided ID does not match any element in the DOM, the operation will not proceed. This allows developers to control exactly where the files list appears in the application's interface.

Default value

"null"
Try a demo showcasing the appendTo property.

Example

Set the appendTo property. 

 <smart-file-upload append-to='div1'></smart-file-upload>

Set the appendTo property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.appendTo = ''div2'';

Get the appendTo property. 

 const fileupload = document.querySelector('smart-file-upload');
 let appendTo = fileupload.appendTo;

autoUploadboolean

Determines whether files are automatically uploaded immediately after they are selected by the user. When set to true, the upload process begins as soon as files are chosen; when false, uploading must be triggered manually.

Default value

false

Example

Set the autoUpload property. 

 <smart-file-upload auto-upload></smart-file-upload>

Set the autoUpload property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.autoUpload = false;

Get the autoUpload property. 

 const fileupload = document.querySelector('smart-file-upload');
 let autoUpload = fileupload.autoUpload;

directoryboolean

Enables users to upload an entire directory at once, including all files contained within any nested subfolders. When this option is selected, the upload process will automatically include every file from the selected directory and its subdirectories. Note: This feature is currently supported only in Firefox and Chrome browsers.

Default value

false
Try a demo showcasing the directory property.

Example

Set the directory property. 

 <smart-file-upload directory></smart-file-upload>

Set the directory property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.directory = false;

Get the directory property. 

 const fileupload = document.querySelector('smart-file-upload');
 let directory = fileupload.directory;

disabledboolean

Controls whether the element is interactive or not. When enabled, the element can be interacted with by the user; when disabled, the element appears inactive and does not respond to user input.

Default value

false

Example

Set the disabled property. 

 <smart-file-upload disabled></smart-file-upload>

Set the disabled property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.disabled = false;

Get the disabled property. 

 const fileupload = document.querySelector('smart-file-upload');
 let disabled = fileupload.disabled;

dropZoneany

Specifies a custom container element to serve as the drop zone for file uploads. When files are dropped onto this container, they will be added to the fileUpload component’s file list. If the 'dropZone' property is set to true, the component will use its internal default drop zone. If 'dropZone' is assigned the ID of an existing HTML element in the DOM, that particular element will be used as the drop zone area for file uploads instead. This allows for flexible placement and styling of the drop zone within your application.

Try a demo showcasing the dropZone property.

Example

Set the dropZone property. 

 <smart-file-upload drop-zone='div1'></smart-file-upload>

Set the dropZone property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.dropZone = 'div2';

Get the dropZone property. 

 const fileupload = document.querySelector('smart-file-upload');
 let dropZone = fileupload.dropZone;

hideFooterboolean

Conceals the entire footer section, including all of its contents—specifically the "Upload All," "Pause All," and "Close All" buttons—preventing users from accessing these actions.

Default value

false

Example

Set the hideFooter property. 

 <smart-file-upload hide-footer></smart-file-upload>

Set the hideFooter property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.hideFooter = false;

Get the hideFooter property. 

 const fileupload = document.querySelector('smart-file-upload');
 let hideFooter = fileupload.hideFooter;

itemTemplateany

Enhances the file item display by applying a custom template to each item in the uploaded files list. This allows you to define the appearance and layout of uploaded file entries, enabling features such as displaying file names, sizes, icons, previews, or custom actions within each file item.

Try a demo showcasing the itemTemplate property.

Example

Set the itemTemplate property. 

 <smart-file-upload item-template='div1'></smart-file-upload>

Set the itemTemplate property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.itemTemplate = 'div2';

Get the itemTemplate property. 

 const fileupload = document.querySelector('smart-file-upload');
 let itemTemplate = fileupload.itemTemplate;

unlockKeystring

Defines the unlockKey property, which is used to retrieve or assign the unique key required to unlock access to the product. Setting this key grants authorization for product usage, while getting it returns the current unlock key in use.

Default value

""

Example

Set the unlockKey property. 

 <smart-file-upload unlock-key=''></smart-file-upload>

Set the unlockKey property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.unlockKey = '1111-2222-3333-4444-5555';

Get the unlockKey property. 

 const fileupload = document.querySelector('smart-file-upload');
 let unlockKey = fileupload.unlockKey;

localestring

Specifies or retrieves the current language setting for displaying messages. This property works together with the messages property to select the appropriate set of localized text based on the chosen language code (e.g., "en", "fr", "es"). Use this property to dynamically change or access the language used in your application's user interface.

Default value

"en"
Try a demo showcasing the locale property.

Example

Set the locale property. 

 <smart-file-upload locale='de'></smart-file-upload>

Set the locale property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.locale = 'fr';

Get the locale property. 

 const fileupload = document.querySelector('smart-file-upload');
 let locale = fileupload.locale;

localizeFormatFunctionfunction | null

A callback function that allows you to customize the format of messages returned by the Localization Module. Use this to modify how localized messages are structured or displayed before they are delivered to your application.

Example

Set the localizeFormatFunction property. 

 <smart-file-upload localize-format-function='function(defaultMessage, message, messageArguments){return '...'}'></smart-file-upload>

Set the localizeFormatFunction property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.localizeFormatFunction = function(defaultMessage, message, messageArguments){return '...'};

Get the localizeFormatFunction property. 

 const fileupload = document.querySelector('smart-file-upload');
 let localizeFormatFunction = fileupload.localizeFormatFunction;

messagesobject

Configures the text labels displayed in the widget interface, enabling support for localization and customization of user-facing messages. The localization object should contain the following fields: browse, pauseFile, cancelFile, uploadFile, pauseAll, cancelAll, and uploadAll—each representing the corresponding action's text label. For optimal results and proper display, set these localization messages before the widget element is initialized.

Default value




"en": {

"propertyUnknownType": "'{{name}}' property is with undefined 'type' member!",

"propertyInvalidValue": "Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!",

"propertyInvalidValueType": "Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!",

"elementNotInDOM": "Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.",

"moduleUndefined": "Module is undefined.",

"missingReference": "{{elementType}}: Missing reference to {{files}}.",

"htmlTemplateNotSuported": "{{elementType}}: Browser doesn't support HTMLTemplate elements.",

"invalidTemplate": "{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM.",

"browse": "Browse",

"uploadFile": "Upload File",

"cancelFile": "Cancel File",

"pauseFile": "Pause File",

"uploadAll": "Upload All",

"cancelAll": "Cancel All",

"pauseAll": "Pause All",

"totalFiles": "Total files: ",

"connectionError": "{{elementType}}: File Upload requires connection to the server.",

"wrongItemIndex": "{{elementType}}: There is no file with such an index in the list of uploaded files.",

"tooLongFileName": "{{elementType}}: File name is too long."

}

Try a demo showcasing the messages property.

Example

Set the messages property. 

 <smart-file-upload messages='{"de":{"propertyUnknownType":"Die Eigenschaft '{{name}}' hat ein nicht definiertes 'type'-Member!","propertyInvalidValue":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualValue}}, Erwarteter Wert: {{value}}!","propertyInvalidValueType":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualType}}, Erwarteter Wert: {{type}}!","elementNotInDOM":"Element existiert nicht in DOM! Bitte fugen Sie das Element zum DOM hinzu, bevor Sie eine Methode aufrufen.","moduleUndefined":"Modul ist nicht definiert.","missingReference":"{{elementType}}: Fehlender Verweis auf {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser unterstutzt keine HTMLTemplate-Elemente.","invalidTemplate":"{{elementType}}: '{{property}}' Die Eigenschaft akzeptiert eine Zeichenfolge, die mit der ID eines HTMLTemplate-Elements aus dem DOM ubereinstimmen muss.","browse":"Durchsuche","uploadFile":"Datei hochladen","cancelFile":"Datei abbrechen","pauseFile":"Datei anhalten","uploadAll":"Alles hochladen","cancelAll":"Alle Absagen","pauseAll":"Alles pausieren","totalFiles":"Gesamtdateien:","connectionError":"{{elementType}}: Der Datei-Upload erfordert eine Verbindung zum Server.","wrongItemIndex":"{{elementType}}: Es gibt keine Datei mit einem solchen Index in der Liste der hochgeladenen Dateien.","tooLongFileName":"{{elementType}}: Dateiname ist zu lang."}}'></smart-file-upload>

Set the messages property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.messages = {"en":{"propertyUnknownType":"'{{name}}' property is with undefined 'type' member!","propertyInvalidValue":"Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!","propertyInvalidValueType":"Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!","elementNotInDOM":"Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.","moduleUndefined":"Module is undefined.","missingReference":"{{elementType}}: Missing reference to {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser doesn't support HTMLTemplate elements.","invalidTemplate":"{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM.","browse":"Browse","uploadFile":"Upload File","cancelFile":"Cancel File","pauseFile":"Pause File","uploadAll":"Upload All","cancelAll":"Cancel All","pauseAll":"Pause All","totalFiles":"Total files: ","connectionError":"{{elementType}}: File Upload requires connection to the server.","wrongItemIndex":"{{elementType}}: There is no file with such an index in the list of uploaded files.","tooLongFileName":"{{elementType}}: File name is too long."}};

Get the messages property. 

 const fileupload = document.querySelector('smart-file-upload');
 let messages = fileupload.messages;

multipleboolean

Specifies or retrieves whether users are permitted to select and upload multiple items simultaneously. When enabled, users can choose more than one file or item within the upload interface.

Default value

false
Try a demo showcasing the multiple property.

Example

Set the multiple property. 

 <smart-file-upload multiple></smart-file-upload>

Set the multiple property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.multiple = false;

Get the multiple property. 

 const fileupload = document.querySelector('smart-file-upload');
 let multiple = fileupload.multiple;

namestring

Gets or sets the name attribute of the hidden file input element. This name is used as the key in the form data when files are uploaded to the server via the URL specified in the uploadUrl property.

Default value

""

Example

Set the name property. 

 <smart-file-upload name='fileUploadName'></smart-file-upload>

Set the name property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.name = 'fileUploadNewName';

Get the name property. 

 const fileupload = document.querySelector('smart-file-upload');
 let name = fileupload.name;

readonlyboolean

When an element is set to readonly, users can view its content but cannot modify or edit it. However, unlike disabled elements, readonly elements remain focusable and their content can typically still be selected and copied. This property is commonly applied to input fields and textareas to prevent changes while allowing visibility and text selection.

Default value

false

Example

Set the readonly property. 

 <smart-file-upload readonly></smart-file-upload>

Set the readonly property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.readonly = true;

Get the readonly property. 

 const fileupload = document.querySelector('smart-file-upload');
 let readonly = fileupload.readonly;

responseHandlerfunction | null

A callback function designed to process server responses, allowing you to handle successful results as well as different error codes and statuses returned from the server. This enables customized handling of success, failure, and edge-case scenarios based on the server’s response.

Example

Set the responseHandler property. 

 <smart-file-upload response-handler='function(xhr){ if(xhr.readyState === 4 && xhr.status === 200) {console.log(xhr.responseText);}}'></smart-file-upload>

Set the responseHandler property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.responseHandler = function(xhr){ if(xhr.status === 404) {console.log('Not Found');}};

Get the responseHandler property. 

 const fileupload = document.querySelector('smart-file-upload');
 let responseHandler = fileupload.responseHandler;

rightToLeftboolean

Sets or retrieves a value that determines whether the element's alignment supports right-to-left (RTL) text direction, which is commonly used for languages such as Arabic or Hebrew. When enabled, the element and its content are visually aligned to accommodate RTL locales, ensuring proper display and user interface behavior for RTL language users.

Default value

false
Try a demo showcasing the rightToLeft property.

Example

Set the rightToLeft property. 

 <smart-file-upload right-to-left></smart-file-upload>

Set the rightToLeft property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.rightToLeft = true;

Get the rightToLeft property. 

 const fileupload = document.querySelector('smart-file-upload');
 let rightToLeft = fileupload.rightToLeft;

setHeadersfunction | null

A callback function that allows you to modify or set custom headers for the XMLHttpRequest (XHR) used during the file upload process. This function receives the XHR object as a parameter, enabling you to add, update, or remove HTTP headers before the request is sent.

Example

Set the setHeaders property. 

 <smart-file-upload set-headers='function(xhr, file){ xhr.setRequestHeader("Cache-Control", "no-cache"); }}'></smart-file-upload>

Set the setHeaders property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.setHeaders = function(xhr, file){ xhr.setRequestHeader("X-File-Name", file.fileName); }};

Get the setHeaders property. 

 const fileupload = document.querySelector('smart-file-upload');
 let setHeaders = fileupload.setHeaders;

showProgressboolean

Displays a visual progress bar at the bottom of each item being uploaded, providing real-time feedback on the upload status. The progress bar dynamically updates to reflect the current percentage of the upload completed for each individual item, allowing users to easily track the progress of their uploads.

Default value

false
Try a demo showcasing the showProgress property.

Example

Set the showProgress property. 

 <smart-file-upload show-progress></smart-file-upload>

Set the showProgress property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.showProgress = false;

Get the showProgress property. 

 const fileupload = document.querySelector('smart-file-upload');
 let showProgress = fileupload.showProgress;

themestring

Specifies the theme to be applied to the element. The selected theme controls the visual appearance—including colors, fonts, and overall style—ensuring that the element’s look is consistent with the desired design scheme.

Default value

""

Example

Set the theme property. 

 <smart-file-upload theme='blue'></smart-file-upload>

Set the theme property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.theme = 'red';

Get the theme property. 

 const fileupload = document.querySelector('smart-file-upload');
 let theme = fileupload.theme;

uploadUrlstring

Specifies or retrieves the URL endpoint to which files will be uploaded. This property directly maps to the action attribute of the upload form. For instance, the uploadUrl property can be set to the path of a server-side script, such as a PHP, Node.js, or ASP.NET file, responsible for processing and handling the file upload operation on the server. Use this property to define where uploaded files should be sent for server-side handling.

Default value

""
Try a demo showcasing the uploadUrl property.

Example

Set the uploadUrl property. 

 <smart-file-upload upload-url='localhost'></smart-file-upload>

Set the uploadUrl property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.uploadUrl = 'localhost/fileUpload';

Get the uploadUrl property. 

 const fileupload = document.querySelector('smart-file-upload');
 let uploadUrl = fileupload.uploadUrl;

unfocusableboolean

If set to true, the element is not focusable and cannot receive keyboard or programmatic focus.

Default value

false

Example

Set the unfocusable property. 

 <smart-file-upload unfocusable></smart-file-upload>

Set the unfocusable property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.unfocusable = false;

Get the unfocusable property. 

 const fileupload = document.querySelector('smart-file-upload');
 let unfocusable = fileupload.unfocusable;

removeUrlstring

Sets or retrieves the URL endpoint used for the remove operation. This property corresponds to the form's action attribute and determines where the form data is submitted when a remove action is triggered. For example, the removeUrl property can be set to the path of a server-side script, such as a PHP file, which processes and handles the remove request on the backend.

Default value

""
Try a demo showcasing the removeUrl property.

Example

Set the removeUrl property. 

 <smart-file-upload remove-url='localhost'></smart-file-upload>

Set the removeUrl property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.removeUrl = 'localhost/fileUpload';

Get the removeUrl property. 

 const fileupload = document.querySelector('smart-file-upload');
 let removeUrl = fileupload.removeUrl;

valueany

Retrieves the value of the uploaded file, such as the file’s name, path, size, or content, depending on the context and configuration of the file upload input. This function allows access to the selected file’s details for further processing, validation, or storage.

Example

Set the value property. 

 <smart-file-upload value=''></smart-file-upload>

Set the value property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.value = ;

Get the value property. 

 const fileupload = document.querySelector('smart-file-upload');
 let value = fileupload.value;

validateFilefunction | null

Callback invoked immediately after files are selected to perform validation. Should return a boolean value: if true, the file is accepted; if false, the file is removed from the selection list and a 'validationError' event is triggered.

Example

Set the validateFile property. 

 <smart-file-upload validate-file='function(file){ if (file.size > 204800) { return false; } return true; }'></smart-file-upload>

Set the validateFile property by using the HTML Element's instance. 

 const fileupload = document.querySelector('smart-file-upload');
 fileupload.validateFile = function(file){ if (file.name.length > 255) { return false; } return true; };

Get the validateFile property. 

 const fileupload = document.querySelector('smart-file-upload');
 let validateFile = fileupload.validateFile;

Events

fileSelectedCustomEvent

This event is triggered whenever a user selects a file, such as through a file input element. It occurs immediately after the file selection is made and can be used to handle or validate the chosen file(s) before further processing, such as uploading or previewing them.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onFileSelected

Arguments

evCustomEvent
ev.detailObject
ev.detail.filename - The name of the selected file.
ev.detail.type - The type of the selected file.
ev.detail.size - The size of the selected file.
ev.detail.index - The index of the selected file.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the fileSelected event.

Example

Set up the event handler of fileSelected event. 

const fileupload = document.querySelector('smart-file-upload');
fileupload.addEventListener('fileSelected', function (event) {
    const detail = event.detail,
        filename = detail.filename,
        type = detail.type,
        size = detail.size,
        index = detail.index;

	// event handling code goes here.
})

uploadCanceledCustomEvent

This event is triggered when a user actively cancels an ongoing file upload process. It indicates that the file transfer has been intentionally terminated before completion, either by user action or programmatic intervention.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onUploadCanceled

Arguments

evCustomEvent
ev.detailObject
ev.detail.filename - The name of the canceled file.
ev.detail.type - The type of the canceled file.
ev.detail.size - The size of the canceled file.
ev.detail.index - The index of the canceled file.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the uploadCanceled event.

Example

Set up the event handler of uploadCanceled event. 

const fileupload = document.querySelector('smart-file-upload');
fileupload.addEventListener('uploadCanceled', function (event) {
    const detail = event.detail,
        filename = detail.filename,
        type = detail.type,
        size = detail.size,
        index = detail.index;

	// event handling code goes here.
})

uploadCompletedCustomEvent

This event is triggered when a file upload process has finished, indicating that the file has been successfully transmitted to the server or the upload has reached its final state (either success or failure). It can be used to execute follow-up actions, such as displaying a confirmation message, updating the user interface, or processing the uploaded file, once the upload operation is complete.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onUploadCompleted

Arguments

evCustomEvent
ev.detailObject
ev.detail.filename - The name of the canceled file.
ev.detail.type - The type of the canceled file.
ev.detail.size - The size of the canceled file.
ev.detail.index - The index of the canceled file.
ev.detail.status - The status of the uploaded file. Whether there was an error or success.
ev.detail.serverResponse - The response of the remote server.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the uploadCompleted event.

Example

Set up the event handler of uploadCompleted event. 

const fileupload = document.querySelector('smart-file-upload');
fileupload.addEventListener('uploadCompleted', function (event) {
    const detail = event.detail,
        filename = detail.filename,
        type = detail.type,
        size = detail.size,
        index = detail.index,
        status = detail.status,
        serverResponse = detail.serverResponse;

	// event handling code goes here.
})

uploadErrorCustomEvent

This event is triggered if an error occurs during the file upload process, causing the upload to fail. It provides information about the failure, allowing you to implement custom error handling or user notifications when a file cannot be successfully uploaded.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onUploadError

Arguments

evCustomEvent
ev.detailObject
ev.detail.filename - The name of the canceled file.
ev.detail.type - The type of the canceled file.
ev.detail.size - The size of the canceled file.
ev.detail.index - The index of the canceled file.
ev.detail.status - The status of the uploaded file. Whether there was an error or success.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the uploadError event.

Example

Set up the event handler of uploadError event. 

const fileupload = document.querySelector('smart-file-upload');
fileupload.addEventListener('uploadError', function (event) {
    const detail = event.detail,
        filename = detail.filename,
        type = detail.type,
        size = detail.size,
        index = detail.index,
        status = detail.status;

	// event handling code goes here.
})

uploadPausedCustomEvent

This event is triggered when an ongoing file upload process is temporarily halted by the user or application. It indicates that the upload is not complete and may be resumed or canceled at a later time. Event listeners can use this event to update the user interface, save upload progress, or handle other logic related to the paused upload state.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onUploadPaused

Arguments

evCustomEvent
ev.detailObject
ev.detail.filename - The name of the paused file.
ev.detail.type - The type of the paused file.
ev.detail.size - The size of the paused file.
ev.detail.index - The index of the paused file.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the uploadPaused event.

Example

Set up the event handler of uploadPaused event. 

const fileupload = document.querySelector('smart-file-upload');
fileupload.addEventListener('uploadPaused', function (event) {
    const detail = event.detail,
        filename = detail.filename,
        type = detail.type,
        size = detail.size,
        index = detail.index;

	// event handling code goes here.
})

uploadStartedCustomEvent

This event is triggered when a file upload process initiates, signaling that the uploading of one or more files has begun. It can be used to perform preparatory actions such as updating the user interface, initializing progress indicators, or logging the start of the file transfer.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onUploadStarted

Arguments

evCustomEvent
ev.detailObject
ev.detail.filename - The name of the file that is being uploaded.
ev.detail.type - The type of the file that is being uploaded.
ev.detail.size - The size of the file that is being uploaded.
ev.detail.index - The index of the file that is being uploaded.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the uploadStarted event.

Example

Set up the event handler of uploadStarted event. 

const fileupload = document.querySelector('smart-file-upload');
fileupload.addEventListener('uploadStarted', function (event) {
    const detail = event.detail,
        filename = detail.filename,
        type = detail.type,
        size = detail.size,
        index = detail.index;

	// event handling code goes here.
})

validationErrorCustomEvent

This event is triggered when the user-defined 'validateFile' callback function returns a failure result, indicating that the provided file did not meet the specified validation criteria.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onValidationError

Arguments

evCustomEvent
ev.detailObject
ev.detail.filename - The name of the file which validation has failed.
ev.detail.type - The type of the file which validation has failed.
ev.detail.size - The size of the file which validation has failed.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the validationError event.

Example

Set up the event handler of validationError event. 

const fileupload = document.querySelector('smart-file-upload');
fileupload.addEventListener('validationError', function (event) {
    const detail = event.detail,
        filename = detail.filename,
        type = detail.type,
        size = detail.size;

	// event handling code goes here.
})

Methods

browse(): void

Displays a popup dialog that allows the user to browse their local device and select a file to upload or process.


Invoke the browse method.

const fileupload = document.querySelector('smart-file-upload');
fileupload.browse();

cancelAll(): void

Cancels all currently selected files. This action removes the files from the selection list and ensures that they are not uploaded. Any ongoing or pending uploads for these files are also stopped, preventing them from being transferred to the server.


Invoke the cancelAll method.

const fileupload = document.querySelector('smart-file-upload');
fileupload.cancelAll();

cancelFile( index: number): void

Cancels the specified file's upload process. This action immediately removes the file from the file list and prevents it from being uploaded or processed any further.

Arguments

indexnumber

Index of the file which will be canceled.


Invoke the cancelFile method.

const fileupload = document.querySelector('smart-file-upload');
fileupload.cancelFile("1");

pauseAll(): void

Pauses the upload process for all files, temporarily halting any active uploads. While uploads are paused and new uploads cannot be started, the files themselves remain visible and accessible in the file list. No files are removed or lost during this pause; uploading can be resumed at a later time.


Invoke the pauseAll method.

const fileupload = document.querySelector('smart-file-upload');
fileupload.pauseAll();

pauseFile( id: number): void

Pauses the upload process for the file at the specified index. The upload for this file is temporarily suspended, preventing any data transfer, but the file itself remains listed in the upload queue. This allows for the upload to be resumed or managed at a later time without removing the file from the list.

Arguments

idnumber

Index of the file which will be paused.


Invoke the pauseFile method.

const fileupload = document.querySelector('smart-file-upload');
fileupload.pauseFile("1");

uploadAll(): void

Uploads every file selected by the user to the server. Handles multiple files simultaneously and ensures each file is processed for upload.


Invoke the uploadAll method.

const fileupload = document.querySelector('smart-file-upload');
fileupload.uploadAll();

uploadFile( id: number): void

Allows the user to select a file from their local device and upload it to the server for processing or storage.

Arguments

idnumber

Index of the file which will be uploaded.


Invoke the uploadFile method.

const fileupload = document.querySelector('smart-file-upload');
fileupload.uploadFile("1");

CSS Variables

--smart-file-upload-default-widthvar()

Default value

"var(--smart-editor-width)"

Default width of the smartFileUpload

--smart-file-upload-browse-button-widthvar()

Default value

"auto"

Default width of the browse button

--smart-file-upload-browse-button-heightvar()

Default value

"auto"

Default height of the browse button

--smart-file-upload-footer-button-widthvar()

Default value

"auto"

Default height of the smartFileUpload's footer buttons

--smart-file-upload-footer-button-heightvar()

Default value

"auto"

Default height of the smartFileUpload's footer buttons

--smart-file-upload-text-content-uploading-startvar()

Default value

"'Connecting ...'"

Default text content of the pseudo element shown when upload starts.

--smart-file-upload-text-content-uploadingvar()

Default value

"'Uploading ...'"

Default text content of the pseudo element shown during the upload.

--smart-file-upload-text-content-errorvar()

Default value

"'Upload error!'"

Default text content of the pseudo element shown on error.

--smart-file-upload-text-content-pausevar()

Default value

"'Upload paused!'"

Default text content of the pseudo element shown when upload is paused.

--smart-file-upload-text-content-drop-zonevar()

Default value

"'Drag files here'"

Default text content of the pseudo element shown where is the drop zone.

--smart-file-upload-text-content-drop-zone-overvar()

Default value

"'Drop here \e824'"

Default text content of the pseudo element shown when dragged files are over the drop zone.

--smart-file-upload-container-min-heightvar()

Default value

"60px"

Sets minimmum height of the drop zone and file zone containers.

--smart-file-upload-total-files-min-heightvar()

Default value

"20px"

Sets min height of the container where total numbers of items is displayed.