# new FileUploadComponent()
This component provides a user interface for uploading files with support for drag-and-drop, file validation, and preview functionality. It integrates seamlessly with Angular reactive forms and supports multiple file uploads, directory mode, and custom file size limits.
File upload component for Angular applications.
Example
```typescript
<ngx-decaf-file-upload [formGroup]="formGroup" [name]="'fileInput'" [multiple]="true"></ngx-decaf-file-upload>
```Classes
- FileUploadComponent
Initializes the parent field directive and clears any previous selection state.
Members
string
|
Array.<string>
# accept
Specifies the file types that are allowed for upload, such as images or documents.
Accepted file types for upload.
- Default Value:
- ['image/*']
View Source lib/components/file-upload/file-upload.component.ts, line 133
string
|
Array.<string>
# accept
Specifies the file types that are allowed for upload, such as images or documents.
Accepted file types for upload.
- Default Value:
- ['image/*']
View Source lib/components/file-upload/file-upload.component.ts, line 911
string
|
undefined
# buttonLabel
Specifies the text displayed on the file upload button.
Label for the upload button.
string
|
undefined
# buttonLabel
Specifies the text displayed on the file upload button.
Label for the upload button.
EventEmitter.<IBaseCustomEvent>
# changeEvent
Emits an event containing details about the change in the file upload field.
Event emitted when the file upload field changes.
EventEmitter.<IBaseCustomEvent>
# changeEvent
Emits an event containing details about the change in the file upload field.
Event emitted when the file upload field changes.
number
# dragCounter
Tracks the number of drag events to ensure proper handling of drag-and-drop operations. The counter is incremented on drag enter and decremented on drag leave.
Counter for drag events.
- Default Value:
- 0
View Source lib/components/file-upload/file-upload.component.ts, line 213
boolean
# dragging
This flag is set to true when a file is being dragged over the upload area. It is used to provide visual feedback to the user during drag-and-drop operations.
Indicates whether a drag operation is in progress.
- Default Value:
- false
View Source lib/components/file-upload/file-upload.component.ts, line 204
boolean
# dragging
This flag is set to true when a file is being dragged over the upload area. It is used to provide visual feedback to the user during drag-and-drop operations.
Indicates whether a drag operation is in progress.
- Default Value:
- false
View Source lib/components/file-upload/file-upload.component.ts, line 991
boolean
# enableDirectoryMode
When true, the user can upload entire directories instead of individual files.
Enables directory mode for file uploads.
- Default Value:
- false
View Source lib/components/file-upload/file-upload.component.ts, line 149
boolean
# enableDirectoryMode
When true, the user can upload entire directories instead of individual files.
Enables directory mode for file uploads.
- Default Value:
- false
View Source lib/components/file-upload/file-upload.component.ts, line 929
Array.<IFileUploadError>
# errors
Stores validation errors for files that do not meet the specified criteria, such as file type or size restrictions. Each error includes the file name, size, and error message.
List of errors encountered during file validation.
Array.<IFileUploadError>
# errors
Stores validation errors for files that do not meet the specified criteria, such as file type or size restrictions. Each error includes the file name, size, and error message.
List of errors encountered during file validation.
Array.<File>
# files
Contains the files selected by the user for upload. This array is updated whenever files are added or removed from the upload list.
List of files selected for upload.
Array.<File>
# files
Contains the files selected by the user for upload. This array is updated whenever files are added or removed from the upload list.
List of files selected for upload.
FormControl
# formControl
The specific FormControl instance that manages this field's state, validation, and value. This provides direct access to Angular's reactive forms functionality for this individual field within the broader form structure.
Angular FormControl instance for this field.
FormControl
# formControl
The specific FormControl instance that manages this field's state, validation, and value. This provides direct access to Angular's reactive forms functionality for this individual field within the broader form structure.
Angular FormControl instance for this field.
FormGroup
# formGroup
References the parent form group to which this field belongs. This is necessary for integrating the field with Angular's reactive forms.
Parent form group.
FormGroup
# formGroup
References the parent form group to which this field belongs. This is necessary for integrating the field with Angular's reactive forms.
Parent form group.
number
# maxFileSize
Specifies the maximum size (in MB) for files that can be uploaded.
Maximum file size allowed for upload.
- Default Value:
- 1
View Source lib/components/file-upload/file-upload.component.ts, line 164
number
# maxFileSize
Specifies the maximum size (in MB) for files that can be uploaded.
Maximum file size allowed for upload.
- Default Value:
- 1
View Source lib/components/file-upload/file-upload.component.ts, line 946
boolean
# multiple
When true, the user can select multiple files for upload.
Allows multiple file selection.
- Default Value:
- false
View Source lib/components/file-upload/file-upload.component.ts, line 83
boolean
# multiple
When true, the user can select multiple files for upload.
Allows multiple file selection.
- Default Value:
- false
View Source lib/components/file-upload/file-upload.component.ts, line 855
string
# name
The flat field name used as the form control identifier in immediate parent FormGroup.
Specifies the name of the field, which is used as the FormControl identifier in immediate parent FormGroup. This value must be unique within the immediate parent FormGroup context and should not contain dots or nesting.
string
# name
The flat field name used as the form control identifier in immediate parent FormGroup.
Specifies the name of the field, which is used as the FormControl identifier in immediate parent FormGroup. This value must be unique within the immediate parent FormGroup context and should not contain dots or nesting.
FlexPosition
# position
Controls how child elements are positioned within the container when flex layout is enabled. Options include 'center', 'top', 'bottom', 'left', 'right', and combinations like 'top-left'. This property is only applied when the flex property is true.
Flex positioning of the container's content.
- Default Value:
- 'center'
View Source lib/components/file-upload/file-upload.component.ts, line 125
FlexPosition
# position
Controls how child elements are positioned within the container when flex layout is enabled. Options include 'center', 'top', 'bottom', 'left', 'right', and combinations like 'top-left'. This property is only applied when the flex property is true.
Flex positioning of the container's content.
- Default Value:
- 'center'
View Source lib/components/file-upload/file-upload.component.ts, line 902
string
|
undefined
# previewFile
Stores the data URL of the first file in the upload list for preview purposes. This is typically used to display a thumbnail or preview image.
Preview of the first file in the upload list.
string
|
undefined
# previewFile
Stores the data URL of the first file in the upload list for preview purposes. This is typically used to display a thumbnail or preview image.
Preview of the first file in the upload list.
FunctionLike
|
undefined
# previewHandler
Allows callers to override the default preview behavior with a function-like callback.
Custom handler used to preview the selected file.
FunctionLike
|
undefined
# previewHandler
Allows callers to override the default preview behavior with a function-like callback.
Custom handler used to preview the selected file.
boolean
# required
When true, the field must have a value for the form to be valid. Required fields are typically marked with an indicator in the UI.
Whether the field is required.
boolean
# required
When true, the field must have a value for the form to be valid. Required fields are typically marked with an indicator in the UI.
Whether the field is required.
boolean
# showIcon
When true, an icon is displayed alongside the file upload input.
Whether to show an icon in the file upload field.
- Default Value:
- true
View Source lib/components/file-upload/file-upload.component.ts, line 141
boolean
# showIcon
When true, an icon is displayed alongside the file upload input.
Whether to show an icon in the file upload field.
- Default Value:
- true
View Source lib/components/file-upload/file-upload.component.ts, line 920
Extract.<ElementSize, ('large'|'small'|'default')>
# size
Determines the visual size of the file upload component, such as large, small, or default.
Size of the file upload component.
- Default Value:
- ElementSizes.large
View Source lib/components/file-upload/file-upload.component.ts, line 115
Extract.<ElementSize, ('large'|'small'|'default')>
# size
Determines the visual size of the file upload component, such as large, small, or default.
Size of the file upload component.
- Default Value:
- ElementSizes.large
View Source lib/components/file-upload/file-upload.component.ts, line 891
string
# subType
Lock subtype to 'text' to ensure that the value is processed as a JSON string containing data URLs or Files. This property will be used to avoid validation errors and to determine how the value is processed and emitted.
Specifies the subtype of the file upload.
- Default Value:
- 'text'
View Source lib/components/file-upload/file-upload.component.ts, line 222
string
# subType
Lock subtype to 'text' to ensure that the value is processed as a JSON string containing data URLs or Files. This property will be used to avoid validation errors and to determine how the value is processed and emitted.
Specifies the subtype of the file upload.
- Default Value:
- 'text'
View Source lib/components/file-upload/file-upload.component.ts, line 1012
PossibleInputTypes
# type
Defines the type of input element used for file uploads, such as file or directory.
Specifies the input type for the file upload field.
- Default Value:
- HTML5InputTypes.FILE
View Source lib/components/file-upload/file-upload.component.ts, line 91
PossibleInputTypes
# type
Defines the type of input element used for file uploads, such as file or directory.
Specifies the input type for the file upload field.
- Default Value:
- HTML5InputTypes.FILE
View Source lib/components/file-upload/file-upload.component.ts, line 864
'base64'
|
'files'
# valueType
Determines the format in which the uploaded file's value is returned. Options include 'base64' for base64-encoded strings or 'files' for File objects.
Specifies the value type for the file upload.
- Default Value:
- 'base64'
View Source lib/components/file-upload/file-upload.component.ts, line 100
'base64'
|
'files'
# valueType
Determines the format in which the uploaded file's value is returned. Options include 'base64' for base64-encoded strings or 'files' for File objects.
Specifies the value type for the file upload.
- Default Value:
- 'base64'
View Source lib/components/file-upload/file-upload.component.ts, line 874
Methods
# changeEventEmit() → {void}
Triggers the change event, notifying any listeners that the value has changed. The event contains the updated value, component name, and event type.
Emits the change event for the file upload field.
void
# clearErrors() → {void}
Resets the error state, removing all error messages from the display.
Clears all error messages from the component.
void
# async getDataURLs(filesopt) → {Promise.<(Array.<string>|undefined)>}
Converts the selected image files to data URLs using FileReader. The resulting data URLs can be used for previewing images in the browser.
Retrieves the data URLs for the selected files.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
files |
Array.<File>
|
File
|
<optional> |
The files for which to generate data URLs. If not provided, the currently selected files are used. |
- A promise that resolves to an array of data URLs, or undefined if an error occurs.
Promise.<(Array.<string>|undefined)>
# getFileMime(base64) → {string}
Parses the data: prefix and returns the embedded MIME type so files can be reconstructed
with the correct content type.
Extracts the MIME type from a base64 data URL.
Parameters:
| Name | Type | Description |
|---|---|---|
base64 |
string
|
The base64 data URL to inspect. |
- The extracted MIME type or an empty string when none is present.
string
# async getPreview() → {Promise.<void>}
If the first selected file is an image, its data URL is retrieved and set as the preview. If the file is not an image, the preview is cleared.
Retrieves the preview image for the selected files.
Promise.<void>
# handleClear() → {void}
Resets the file upload component by clearing the selected files, preview, and errors. This method is used to reset the component state.
Clears the file list and validation errors.
void
# async handleClickToSelect() → {void}
Simulates a click on the hidden file input element to open the file selection dialog. This method is used to allow users to select files programmatically.
Handles the click event to trigger file selection.
void
# handleDragLeave(event) → {void}
Decrements the drag counter and clears the dragging flag when the counter reaches zero. This method is triggered when the user drags files out of the upload area.
Handles the drag leave event for drag-and-drop file uploads.
Parameters:
| Name | Type | Description |
|---|---|---|
event |
DragEvent
|
The drag leave event. |
void
# handleDragOver(event) → {void}
Sets the dragging flag to true to provide visual feedback during drag-and-drop operations. This method is triggered when the user drags files over the upload area.
Handles the drag over event for drag-and-drop file uploads.
Parameters:
| Name | Type | Description |
|---|---|---|
event |
DragEvent
|
The drag over event. |
void
# handleDrop(event) → {void}
Processes the files dropped by the user, validates them, and updates the file list. This method is triggered when the user drops files onto the upload area.
Handles the drop event for drag-and-drop file uploads.
Parameters:
| Name | Type | Description |
|---|---|---|
event |
DragEvent
|
The drag-and-drop event. |
void
# async handleRemove(index) → {Promise.<void>}
Updates the file list to exclude the file at the specified index. Emits the change event and updates the preview if necessary.
Removes a file from the selection.
Parameters:
| Name | Type | Description |
|---|---|---|
index |
number
|
The index of the file to be removed. |
Promise.<void>
# async handleSelection(event) → {Promise.<void>}
Processes the files selected by the user, validates them, and updates the file list. This method is triggered when the user selects files using the file input element.
Handles the file selection event.
Parameters:
| Name | Type | Description |
|---|---|---|
event |
Event
|
The file selection event. |
Promise.<void>
# async handleSelectionConfirm(files) → {Promise.<void>}
Validates each file in the selection, updates the file list, and emits the change event. If multiple or directory mode is enabled, adds files to the existing list. Otherwise, replaces the existing files with the new selection.
Confirms the file selection and updates the component state.
Parameters:
| Name | Type | Description |
|---|---|---|
files |
Array.<File>
|
The array of files selected by the user. |
Promise.<void>
# async initialize() → {Promise.<void>}
Restores any serialized value back into files and preview data after the parent initialization completes.
Initializes the component value state after the base directive is ready.
- A promise that resolves when initialization is complete.
Promise.<void>
# isBase64String(value) → {boolean}
Supports both raw base64 strings and data:*;base64 URLs for file reconstruction and preview handling.
Checks whether a string is a valid base64 payload or data URL.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
string
|
The string to validate. |
- True when the string matches a base64 or base64 data URL pattern.
boolean
# isImageFile(file) → {boolean}
Determines if the file can be accepted as an image by checking if its type starts with 'image/'.
Checks if a file is an image based on its MIME type.
Parameters:
| Name | Type | Description |
|---|---|---|
file |
File
|
The file to be checked. |
- True if the file is an image, false otherwise.
boolean
# isValidDataURL(dataURL) → {boolean}
Checks if the data URL is a non-empty string and matches the expected pattern for base64-encoded image data URLs. Uses a regular expression to validate the format.
Validates the format of a data URL.
Parameters:
| Name | Type | Description |
|---|---|---|
dataURL |
string
|
undefined
|
The data URL to be validated. |
- True if the data URL is valid, false otherwise.
boolean
# async ngOnDestroy() → {Promise.<void>}
Cleans up the component by calling the parent ngOnDestroy method and clearing the file upload state.
Lifecycle hook that is called when a directive, pipe, or service is destroyed.
Promise.<void>
# async ngOnInit() → {Promise.<void>}
Sets up the component by enabling directory mode if specified, formatting the accepted file types, and converting the maximum file size from megabytes to bytes.
Lifecycle hook that is called after Angular has initialized all data-bound properties of a directive.
Promise.<void>
# async parseValue(revertopt) → {Promise.<(string|void)>}
When revert is false, serializes the selected files into the form value. When true, parses
the current value back into the component file list and restores the preview state.
Converts between the component's internal file state and its serialized value.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
revert |
boolean
|
<optional> |
false | Whether to restore files from the current value instead of serializing them. |
- A serialized value when converting files to a form value, otherwise void.
Promise.<(string|void)>
# async preview(fileopt) → {Promise.<void>}
If the file is an image, its data URL is retrieved and displayed in a modal lightbox. The lightbox shows the image at its natural size, constrained to the viewport dimensions.
Displays a preview of the selected file in a lightbox.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
file |
File
|
string
|
<optional> |
The file to be previewed. If not provided, the current preview file is used. |
Promise.<void>
# readFile(files) → {Promise.<Array.<string>>}
Uses the FileReader API to read each file as a data URL. Returns a promise that resolves to an array of data URLs.
Reads the selected files as data URLs.
Parameters:
| Name | Type | Description |
|---|---|---|
files |
Array.<File>
|
The files to be read. |
- A promise that resolves to an array of data URLs.
Promise.<Array.<string>>
# validateFile(file) → {true|string}
Checks the file type and size against the accepted values and limits. Returns true if the file is valid, or an error code if it is not.
Validates a single file against the component's constraints.
Parameters:
| Name | Type | Description |
|---|---|---|
file |
File
|
The file to be validated. |
- Returns true if valid, error code otherwise.
true
|
string