File Upload
Accessible controlled file picker and drop zone with validation, progress, immutable changes, and explicit consumer-owned upload requests.
- Selector
- ui-file-upload
- Package
- @ngnova/ui/file-upload
Import
import { UiFileUploadComponent } from '@ngnova/ui/file-upload';Usage & variants
Live examples use the public ui-file-upload API, paired with the exact snippet a product team would paste into an Angular app.
Release asset upload
Accessible controlled file picker and drop zone with validation, progress, immutable changes, and explicit consumer-owned upload requests.
Drop files here
PNG, JPG, or PDF up to 5 MB
Production guidance
Use these notes to decide when the component belongs in a product workflow and what to verify before shipping.
When to use
Use for attachments, media, imports, and other workflows where users choose local files.
Watch for
accept is advisory at the browser picker and is validated again before filesChange.
Product recipes
Apply File Upload in distinct, copyable product scenarios—not just an isolated component state.
Validated controlled upload
The application owns accepted files and performs uploads only after an explicit request.
1 2 3 4 5 6 7 8 9 10 11 12
<ui-file-upload
[files]="files()"
(filesChange)="files.set($event)"
(rejected)="showRejections($event)"
(uploadRequested)="upload($event)"
[progress]="progressByFile()"
accept="image/*,.pdf"
[maxFiles]="5"
[maxFileSize]="5000000"
[maxTotalSize]="15000000"
ariaLabel="Project attachments"
/>Profile photo upload
Constrain a single image upload and communicate the accepted format before selection.
1 2 3 4 5 6 7 8
<ui-file-upload
label="Profile photo"
helperText="PNG or JPEG, up to 2 MB."
accept="image/png,image/jpeg"
[multiple]="false"
[maxFileSize]="2097152"
(filesChange)="previewPhoto($event)"
/>API Reference
Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.
Inputs
files [] readonly File[] Controlled accepted files.
accept '' string Comma-separated extensions or MIME rules.
multiple true boolean Allows more than one controlled file.
disabled false boolean Disables picker, drop, removal, clear, and upload actions.
autoUpload false boolean Requests upload immediately for newly accepted files.
maxFiles 0 number Maximum file count; zero is unlimited.
maxFileSize 0 number Maximum bytes per file; zero is unlimited.
maxTotalSize 0 number Maximum total bytes; zero is unlimited.
progress {} Readonly<Record<string, number>> Progress by stable file key, clamped from 0 through 100.
ariaLabel 'File upload' string Accessible name for the upload section.
chooseLabel 'Choose files' string Localized picker action label.
dropLabel 'Drop files here' string Localized drop-zone heading.
helperText 'or choose files from your device' string Visible format and limit guidance.
clearLabel 'Clear' string Localized clear action label.
uploadLabel 'Upload' string Localized upload request label.
fileListAriaLabel 'Selected files' string Accessible name for accepted files.
removeAriaLabel 'Remove' string Accessible-label prefix for removal.
rejectionText 'Some files could not be added.' string Localized validation alert.
| Name | Type | Default | Description |
|---|---|---|---|
files | readonly File[] | [] | Controlled accepted files. |
accept | string | '' | Comma-separated extensions or MIME rules. |
multiple | boolean | true | Allows more than one controlled file. |
disabled | boolean | false | Disables picker, drop, removal, clear, and upload actions. |
autoUpload | boolean | false | Requests upload immediately for newly accepted files. |
maxFiles | number | 0 | Maximum file count; zero is unlimited. |
maxFileSize | number | 0 | Maximum bytes per file; zero is unlimited. |
maxTotalSize | number | 0 | Maximum total bytes; zero is unlimited. |
progress | Readonly<Record<string, number>> | {} | Progress by stable file key, clamped from 0 through 100. |
ariaLabel | string | 'File upload' | Accessible name for the upload section. |
chooseLabel | string | 'Choose files' | Localized picker action label. |
dropLabel | string | 'Drop files here' | Localized drop-zone heading. |
helperText | string | 'or choose files from your device' | Visible format and limit guidance. |
clearLabel | string | 'Clear' | Localized clear action label. |
uploadLabel | string | 'Upload' | Localized upload request label. |
fileListAriaLabel | string | 'Selected files' | Accessible name for accepted files. |
removeAriaLabel | string | 'Remove' | Accessible-label prefix for removal. |
rejectionText | string | 'Some files could not be added.' | Localized validation alert. |
Outputs
filesChange OutputEmitterRef<readonly File[]> Emits a frozen next accepted-file collection.
rejected OutputEmitterRef<readonly UiFileUploadRejection[]> Emits frozen files and machine-readable rejection reasons.
uploadRequested OutputEmitterRef<UiFileUploadRequest> Requests consumer upload work without hidden network behavior.
| Name | Type | Description |
|---|---|---|
filesChange | OutputEmitterRef<readonly File[]> | Emits a frozen next accepted-file collection. |
rejected | OutputEmitterRef<readonly UiFileUploadRejection[]> | Emits frozen files and machine-readable rejection reasons. |
uploadRequested | OutputEmitterRef<UiFileUploadRequest> | Requests consumer upload work without hidden network behavior. |
Accessibility
- The visually hidden native input remains labeled; choose, clear, upload, and remove actions are native buttons.
- Accepted files use a named list, progress uses progressbar semantics, and validation failures use role alert.
- Visible helper text should describe accepted formats and limits before users choose files.
Keyboard behavior
- All actions use native Tab, Enter, and Space behavior with visible keyboard focus.
- Drag and drop is an enhancement; every workflow remains available through the choose-files button.
Testing guidance
- Assert type/size/count/total/duplicate rejection, immutable controlled changes, auto/manual requests, progress, disabled behavior, localization, and UiFileUploadHarness actions.