Component v1.1.0 Foundations

File Upload

Accessible controlled file picker and drop zone with validation, progress, immutable changes, and explicit consumer-owned upload requests.

API Stable 2.1 WCAG notes Ready Dark mode
Selector
ui-file-upload
Package
@ngnova/ui/file-upload

Import

Standalone Tailwind v4
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.

API Reference

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.

Angular template ui-file-upload-recipe.example.html
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.

Angular template ui-file-upload-recipe.example.html
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.

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.

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.