# 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>
```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 136
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 789
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 210
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 201
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 861
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 152
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 807
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.
string
|
undefined
# label
Provides a user-friendly label for the file upload input.
Label for the file upload field.
string
|
undefined
# label
Provides a user-friendly label for the file upload input.
Label for the file upload field.
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 161
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 816
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 88
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 735
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 128
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 780
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.
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 144
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 798
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 118
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 769
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 96
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 744
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)>
# 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
# 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 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>
# 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
# ngOnDestroy() → {Promise.<void>|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>
|
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 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>>
# async removeFile(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>
# 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