Form

File Upload

New

Copy page

View as Markdown

Open in ChatGPT

Open in Claude

A drop zone and a list of files for choosing files to upload.

Usage#

app.component.ts

import { WdsFileUploadComponent } from '@wds/angular/file-upload';

The element collects files; it does not send them. Read files (or the form data) and upload them yourself, showing the progress with setFileStatus(). Name the field with a wds-field-label in a wds-field (or label).

Examples#

Default#

Click the drop zone (or press Enter or Space) to open the file picker, or drag a file onto it. Without multiple a new file replaces the previous one. The hint comes from accept and max-size (in bytes); images get a preview.

Cover image

Show code

file-upload-default.ts

import { Component } from '@angular/core';
import { WdsFieldComponent, WdsFieldLabelComponent } from '@wds/angular/field';
import { WdsFileUploadComponent } from '@wds/angular/file-upload';

@Component({
  selector: 'app-file-upload-default-demo',
  imports: [WdsFieldComponent, WdsFieldLabelComponent, WdsFileUploadComponent],
  template: `
    <wds-field class="w-full max-w-md">
      <wds-field-label>Cover image</wds-field-label>
      <wds-file-upload accept="image/*" max-size="5242880"></wds-file-upload>
    </wds-field>
  `,
})
export class FileUploadDefaultDemo {}

Multiple files#

multiple keeps adding files to the list, up to max-files. The same file added twice is listed once.

Attachments

Invoices or photos of receipts.

Show code

file-upload-multiple.ts

import { Component } from '@angular/core';
import { WdsFieldComponent, WdsFieldDescriptionComponent, WdsFieldLabelComponent } from '@wds/angular/field';
import { WdsFileUploadComponent } from '@wds/angular/file-upload';

@Component({
  selector: 'app-file-upload-multiple-demo',
  imports: [WdsFieldComponent, WdsFieldLabelComponent, WdsFieldDescriptionComponent, WdsFileUploadComponent],
  template: `
    <wds-field class="w-full max-w-md">
      <wds-field-label>Attachments</wds-field-label>
      <wds-file-upload multiple max-files="5" max-size="10485760" accept="image/*,.pdf"></wds-file-upload>
      <wds-field-description>Invoices or photos of receipts.</wds-field-description>
    </wds-field>
  `,
})
export class FileUploadMultipleDemo {}

Upload progress and rejected files#

wds-change gives the files; setFileStatus(file, { progress }) shows a progress bar under a file, { error } an error, and null clears it. Files that do not pass accept, max-size or max-files are not added and fire wds-reject with the reason.

Photos

Show code

file-upload-progress.ts

import { Component, signal, viewChild } from '@angular/core';
import type { WdsFileUploadRejectDetail } from '@wds/core/file-upload';
import { WDS_FIELD } from '@wds/angular/field';
import { WdsFileUploadComponent } from '@wds/angular/file-upload';

@Component({
  selector: 'app-file-upload-progress-demo',
  imports: [...WDS_FIELD, WdsFileUploadComponent],
  template: `
    <div class="flex w-full max-w-md flex-col gap-3">
      <wds-field>
        <wds-field-label>Photos</wds-field-label>
        <wds-file-upload
          multiple
          accept="image/*"
          max-size="2097152"
          (wdsChange)="startUploads($event.files)"
          (wdsReject)="showRejected($event)"
        />
      </wds-field>
      @if (rejected()) {
        <p class="m-0 text-sm text-destructive">{{ rejected() }}</p>
      }
    </div>
  `,
})
export class FileUploadProgressDemo {
  private readonly upload = viewChild.required(WdsFileUploadComponent);
  private readonly started = new WeakSet<File>();
  protected readonly rejected = signal('');

  /** The element only collects files; this fake upload shows the progress with setFileStatus(). */
  protected startUploads(files: File[]): void {
    const el = this.upload();
    for (const file of files) {
      if (this.started.has(file)) continue;
      this.started.add(file);
      let progress = 0;
      const timer = setInterval(() => {
        progress = Math.min(100, progress + 10 + Math.random() * 20);
        el.setFileStatus(file, { progress: Math.round(progress) });
        if (progress >= 100) {
          clearInterval(timer);
          setTimeout(() => el.setFileStatus(file, null), 400);
        }
      }, 300);
    }
  }

  protected showRejected(detail: WdsFileUploadRejectDetail): void {
    const why = { size: 'larger than 2 MB', type: 'not an image', count: 'too many files' };
    this.rejected.set(detail.rejected.map(({ file, reason }) => `${file.name}: ${why[reason]}`).join('. '));
  }
}

Custom drop zone#

Content in the default slot replaces the icon, the text and the hint; --wds-file-upload-min-height: 0 makes the zone as low as its content. Use text and icons only: the drop zone is a button.

Resume

Attach a file PDF or DOCX

Show code

file-upload-compact.ts

import { Component } from '@angular/core';
import { WdsFieldComponent, WdsFieldLabelComponent } from '@wds/angular/field';
import { WdsFileUploadComponent } from '@wds/angular/file-upload';

@Component({
  selector: 'app-file-upload-compact-demo',
  imports: [WdsFieldComponent, WdsFieldLabelComponent, WdsFileUploadComponent],
  template: `
    <wds-field class="w-full max-w-md">
      <wds-field-label>Resume</wds-field-label>
      <wds-file-upload accept=".pdf,.docx" class="[--wds-file-upload-min-height:0]">
        <span class="flex items-center gap-2 text-sm">
          <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m21.44 11.05-9.19 9.19a6 6 0 0 1-8.49-8.49l8.57-8.57A4 4 0 1 1 18 8.84l-8.59 8.57a2 2 0 0 1-2.83-2.83l8.49-8.48" /></svg>
          <span><span class="font-medium underline underline-offset-3">Attach a file</span> <span class="text-muted-foreground">PDF or DOCX</span></span>
        </span>
      </wds-file-upload>
    </wds-field>
  `,
})
export class FileUploadCompactDemo {}

Disabled#

disabled blocks the picker and dropping, and excludes the files from the form.

Documents

Uploads are paused during maintenance.

Show code

file-upload-disabled.ts

import { Component } from '@angular/core';
import { WdsFieldComponent, WdsFieldDescriptionComponent, WdsFieldLabelComponent } from '@wds/angular/field';
import { WdsFileUploadComponent } from '@wds/angular/file-upload';

@Component({
  selector: 'app-file-upload-disabled-demo',
  imports: [WdsFieldComponent, WdsFieldLabelComponent, WdsFieldDescriptionComponent, WdsFileUploadComponent],
  template: `
    <wds-field class="w-full max-w-md" disabled>
      <wds-field-label>Documents</wds-field-label>
      <wds-file-upload multiple disabled></wds-file-upload>
      <wds-field-description>Uploads are paused during maintenance.</wds-field-description>
    </wds-field>
  `,
})
export class FileUploadDisabledDemo {}

Forms#

Integration with Angular forms. Pick the API your app uses.

Signal forms#

WdsFileUploadField connects the field to [formField]; the model is File[]. In signal forms required() does not treat an empty array as empty, so check the number of files with validate() (here with requiredError); required() still marks the field as required.

Show code

file-upload-signal-forms.ts

import { Component, computed, signal } from '@angular/core';
import { FormField, FormRoot, form, required, requiredError, validate } from '@angular/forms/signals';
import { WdsButtonComponent } from '@wds/angular/button';
import { WDS_FIELD } from '@wds/angular/field';
import { WdsFileUploadComponent } from '@wds/angular/file-upload';
import { WdsFileUploadField } from '@wds/angular/forms';

interface Claim {
  receipts: File[];
}

@Component({
  selector: 'app-file-upload-signal-forms-demo',
  imports: [FormField, FormRoot, WdsButtonComponent, ...WDS_FIELD, WdsFileUploadComponent, WdsFileUploadField],
  template: `
    <form class="flex w-md max-w-full flex-col gap-6" [formRoot]="claimForm">
      <wds-field [invalid]="showError()">
        <wds-field-label>Receipts</wds-field-label>
        <wds-file-upload [formField]="claimForm.receipts" multiple accept="image/*,.pdf" />
        <wds-field-error [errors]="showError() ? claimForm.receipts().errors() : []" />
      </wds-field>
      <wds-button type="submit" class="self-start">Submit claim</wds-button>
      <p class="m-0 font-mono text-sm text-muted-foreground">Submitted: {{ submitted() }}</p>
    </form>
  `,
})
export class FileUploadSignalFormsDemo {
  protected readonly claim = signal<Claim>({ receipts: [] });
  protected readonly submitted = signal('—');

  protected readonly claimForm = form(
    this.claim,
    (path) => {
      // required() marks the field as required, but in signal forms an empty array is not "empty": check the length too.
      required(path.receipts);
      validate(path.receipts, ({ value }) => (value().length ? undefined : requiredError({ message: 'Add at least one receipt.' })));
    },
    {
      submission: {
        action: async (form) => {
          this.submitted.set(form().value().receipts.map((f) => f.name).join(', '));
        },
      },
    }
  );

  /** The error appears after the user leaves the field or submits the form. */
  protected readonly showError = computed(() => this.claimForm.receipts().touched() && this.claimForm.receipts().invalid());
}

Template-driven#

WdsFileUploadValueAccessor makes ngModel work on wds-file-upload. Inside a <form> the field needs a name.

Show code

file-upload-template-driven.ts

import { Component, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { WdsButtonComponent } from '@wds/angular/button';
import { WDS_FIELD } from '@wds/angular/field';
import { WdsFileUploadComponent } from '@wds/angular/file-upload';
import { WdsFileUploadValueAccessor } from '@wds/angular/forms';

@Component({
  selector: 'app-file-upload-template-driven-demo',
  imports: [FormsModule, WdsButtonComponent, ...WDS_FIELD, WdsFileUploadComponent, WdsFileUploadValueAccessor],
  template: `
    <form class="flex w-md max-w-full flex-col gap-6" (ngSubmit)="submitted.set(names())">
      <wds-field>
        <wds-field-label>Receipts</wds-field-label>
        <wds-file-upload name="receipts" [(ngModel)]="receipts" multiple accept="image/*,.pdf" />
      </wds-field>
      <wds-button type="submit" class="self-start">Submit claim</wds-button>
      <p class="m-0 font-mono text-sm text-muted-foreground">Submitted: {{ submitted() }}</p>
    </form>
  `,
})
export class FileUploadTemplateDrivenDemo {
  protected receipts: File[] = [];
  protected readonly submitted = signal('—');

  protected names(): string {
    return this.receipts.map((f) => f.name).join(', ') || '—';
  }
}

Reactive forms#

The same WdsFileUploadValueAccessor works with formControl and formControlName; an empty list fails Validators.required.

Show code

file-upload-reactive-forms.ts

import { Component, signal } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { WdsButtonComponent } from '@wds/angular/button';
import { WDS_FIELD } from '@wds/angular/field';
import { WdsFileUploadComponent } from '@wds/angular/file-upload';
import { WdsFileUploadValueAccessor } from '@wds/angular/forms';

@Component({
  selector: 'app-file-upload-reactive-forms-demo',
  imports: [ReactiveFormsModule, WdsButtonComponent, ...WDS_FIELD, WdsFileUploadComponent, WdsFileUploadValueAccessor],
  template: `
    <form class="flex w-md max-w-full flex-col gap-6" [formGroup]="claimForm" (ngSubmit)="save()">
      <wds-field [invalid]="receipts.touched && receipts.invalid">
        <wds-field-label>Receipts</wds-field-label>
        <wds-file-upload formControlName="receipts" multiple accept="image/*,.pdf" />
        @if (receipts.touched && receipts.invalid) {
          <wds-field-error>Add at least one receipt.</wds-field-error>
        }
      </wds-field>
      <wds-button type="submit" class="self-start">Submit claim</wds-button>
      <p class="m-0 font-mono text-sm text-muted-foreground">Submitted: {{ submitted() }}</p>
    </form>
  `,
})
export class FileUploadReactiveFormsDemo {
  protected readonly claimForm = new FormGroup({
    // The value is a File[]; an empty list fails Validators.required.
    receipts: new FormControl<File[]>([], { nonNullable: true, validators: Validators.required }),
  });
  protected readonly receipts = this.claimForm.controls.receipts;
  protected readonly submitted = signal('—');

  protected save(): void {
    this.claimForm.markAllAsTouched();
    if (this.claimForm.valid) this.submitted.set(this.receipts.value.map((f) => f.name).join(', '));
  }
}

API References#

wds-file-upload#

A field for files: a drop zone that opens the file picker on click (or Enter and Space) and takes files dragged onto it, and a list of the chosen files with a preview, the size and a remove button. accept, max-size and max-files filter the files as they are added; the rejected ones fire wds-reject. The element does not upload anything: read files (or the form data) and send them yourself. During an upload setFileStatus() shows a progress bar or an error under a file. In a <form> the files are submitted under name, and required validates as in a native file field.

Attributes

Attribute	Type	Default	Description
accept	string	''	Accepted types, as in `<input type="file">`: extensions and MIME types, e.g. `image/*,.pdf`.
multiple	boolean	false	Allows more than one file. Without it a new file replaces the previous one.
max-files.maxFiles	number \| undefined		Largest number of files (with `multiple`).
max-size.maxSize	number \| undefined		Largest size of one file, in bytes (e.g. `5242880` for 5 MB).
name	string	''	Field name in the form; each file is submitted under it.
disabled	boolean	false	Disables the field and excludes it from form submission.
required	boolean	false	At least one file is required for the form to be valid.
invalid	boolean	false	Error state: red border of the drop zone and `aria-invalid`.
hide-list.hideList	boolean	false	Hides the built-in list (e.g. to show the files your own way).
label	string	''	Accessible name of the drop zone when the field is not in a `wds-field` with a label.

Properties

Property	Description
filesFile[]	The chosen files. Setting it replaces the list (e.g. `[]` to clear it).

Events

Event	Description
wds-rejectCustomEvent<WdsFileUploadRejectDetail>	Some of the added files did not pass `accept`, `max-size` or `max-files`.
wds-changeCustomEvent<WdsFileUploadChangeDetail>	Files were added or removed.
wds-removeCustomEvent<WdsFileUploadRemoveDetail>	The user removed a file from the list.

Methods

Method	Description
browse()	Opens the file picker.
addFiles(files: Iterable<File>)	Adds files as if they were dropped (they pass the same checks).
removeFile(file: File)	Removes a file from the list.
clear()	Removes all files.
setFileStatus(file: File, status: WdsFileUploadStatus \| null)	Shows the upload progress (0–100) or an error under a file; `null` removes the status.
formResetCallback()
formDisabledCallback(disabled: boolean)
checkValidity()	Returns `true` when the value is valid; otherwise fires `invalid` on the element.
reportValidity()	Like `checkValidity()`, and shows the browser validation bubble when the value is invalid.
setCustomValidity(message: string)	Sets a custom validation error (an empty string clears it), like `input.setCustomValidity()`.

Slots

Slot	Description
(default)	Content of the drop zone instead of the default icon, text and hint (text and icons only: the drop zone is a button).

CSS parts (::part)

Part	Description
dropzone	The drop zone (a `<button>`).
hint	The hint under the text of the drop zone.
list	The list of files.
file	A row of the list.
remove	The remove button of a row.

CSS custom properties

Property	Description
--wds-file-upload-min-height	Minimum height of the drop zone (default 9rem).

Accessibility#

The drop zone is a native button named by the wds-field-label (or label), with the hint (types, size, number of files) as its description. Dragging and dropping is optional: every file can be added with the keyboard.

Added, removed and rejected files are announced in a status region, e.g. "photo.jpg added." or "2 files not added." Show the reasons for rejected files on the page as well (see the example).

The files are a list; each remove button is named "Remove" with the file name. After a removal focus moves to the next remove button, or back to the drop zone.

An upload progress bar is a progressbar named "Uploading" with the file name. invalid and required set aria-invalid and the validation state, as in a native file field.

Keyboard support#

Key	Function
EnterSpace	On the drop zone: opens the file picker.
Tab	Moves from the drop zone to the remove buttons of the files.
EnterSpace	On a remove button: removes the file.

Usage#

Examples#

Default#

Multiple files#

Upload progress and rejected files#

Custom drop zone#

Disabled#

Forms#

Signal forms#

Template-driven#

Reactive forms#

API References#

wds-file-upload#

Attributes

Properties

Events

Methods

Slots

CSS parts (::part)

CSS custom properties

Accessibility#

Screen reader#

Keyboard support#