ngx-uploader

Angular File Uploader

https://ngx-uploader.petadev.work

Got a Question or Problem?

Do not open issues for general support questions as we want to keep GitHub issues for bug reports and feature requests. You've got much better chances of getting your question answered on Stack Overflow where the questions should be tagged with tag ngx-uploader.

To save your and our time, we will systematically close all issues that are requests for general support and redirect people to Stack Overflow.

Installation

1. Add ngx-uploader module as dependency to your project.

1npm i @angular-ex/uploader --save

2. Include NgxUploaderModule into your main AppModule or in module where you will use it.

1// app.module.ts
2import { NgModule } from '@angular/core';
3import { BrowserModule } from '@angular/platform-browser';
4import { NgxUploaderModule } from 'ngx-uploader';
5
6@NgModule({
7  imports: [BrowserModule, NgxUploaderModule],
8  declarations: [AppComponent]
9})
10export class AppModule {}

or include NgxUploaderModule into your SharedModule. This could be usefull if your project has nested Modules.

1// shared.module.ts
2import { NgModule } from '@angular/core';
3import { CommonModule } from '@angular/common';
4import { NgxUploaderModule } from 'ngx-uploader';
5...
6
7@NgModule({
8  imports: [
9    CommonModule,
10    NgxUploaderModule,
11    ...
12  ],
13  exports: [
14    CommonModule,
15    NgxUploaderModule,
16    ...
17  ],
18  ...
19})
20export class SharedModule {
21}

1// app.module.ts
2import { NgModule } from '@angular/core';
3import { BrowserModule } from '@angular/platform-browser';
4import { SharedModule } from './shared.module';
5
6@NgModule({
7  imports: [BrowserModule, SharedModule],
8  declarations: [AppComponent]
9})
10export class AppModule {}

Data Structures of Events and Uploaded Files

1export interface UploaderOptions {
2  concurrency: number; // number of files uploaded at the same time
3  allowedContentTypes?: string[]; // content types allowed (default *)
4  maxUploads?: number; // max number of files the user can upload
5  maxFileSize?: number; // max size of the file in bytes the user can upload
6}
7
8export interface UploadProgress {
9  status: UploadStatus; // current status of upload for specific file (Queue | Uploading | Done | Canceled)
10  data?: {
11    percentage: number; // percentage of upload already completed
12    speed: number; // current upload speed per second in bytes
13    speedHuman: string; // current upload speed per second in human readable form,
14    eta: number; // estimated time remaining in seconds
15    etaHuman: string; // estimated time remaining in human readable format
16  };
17}
18
19export interface UploadFile {
20  id: string; // unique id of uploaded file instance
21  fileIndex: number; // fileIndex in internal ngx-uploader array of files
22  lastModifiedDate: Date; // last modify date of the file (Date object)
23  name: string; // original name of the file
24  size: number; // size of the file in bytes
25  type: string; // mime type of the file
26  form: FormData; // FormData object (you can append extra data per file, to this object)
27  progress: UploadProgress;
28  response?: any; // response when upload is done (parsed JSON or string)
29  responseStatus?: number; // response status code when upload is done
30  responseHeaders?: { [key: string]: string }; // response headers when upload is done
31}
32
33// output events emitted by ngx-uploader
34export interface UploadOutput {
35  type:
36    | 'addedToQueue'
37    | 'allAddedToQueue'
38    | 'uploading'
39    | 'done'
40    | 'removed'
41    | 'start'
42    | 'cancelled'
43    | 'dragOver'
44    | 'dragOut'
45    | 'drop';
46  file?: UploadFile;
47  nativeFile?: File; // native javascript File object, can be used to process uploaded files in other libraries
48}
49
50// input events that user can emit to ngx-uploader
51export interface UploadInput {
52  type: 'uploadAll' | 'uploadFile' | 'cancel' | 'cancelAll' | 'remove' | 'removeAll';
53  url?: string; // URL to upload file to
54  method?: string; // method (POST | PUT)
55  id?: string; // unique id of uploaded file
56  fieldName?: string; // field name (default 'file')
57  fileIndex?: number; // fileIndex in internal ngx-uploader array of files
58  file?: UploadFile; // uploading file
59  data?: { [key: string]: string | Blob }; // custom data sent with the file
60  headers?: { [key: string]: string }; // custom headers
61  includeWebKitFormBoundary?: boolean; // If false, only the file is send trough xhr.send (WebKitFormBoundary is omit)
62  concurrency?: number; // concurrency of how many files can be uploaded in parallel (default is 0 which means unlimited)
63  withCredentials?: boolean; // apply withCredentials option
64}

Upload Restrictions

With version 4.2.1 we've introduced restrictions for Content-Types. To not break the behaviour of previous releases, there are no restrictions by default at all.

Look at app-home.component.ts for an example of Content-Type restriction.

If you want to toast a message for the rejected file, add this to your onUploadOutput method.

1onUploadOutput(output: UploadOutput): void {
2....
3} else if (output.type === 'rejected' && typeof output.file !== 'undefined') {
4  // console.log(output.file.name + ' rejected');
5}
6...

Token Authorization

If you have to upload files with Token Authorization, you can set the header in startUpload as follows.

1startUpload(): void {
2  let token = this.myToken;  // <----  get token
3  const event: UploadInput = {
4    type: 'uploadAll',
5    url: 'http://ngx-uploader.petadev.work/upload',
6    method: 'POST',
7    headers: { 'Authorization': 'JWT ' + token },  // <----  set headers
8    data: { foo: 'bar' },
9    includeWebKitFormBoundary: true // <----  set WebKitFormBoundary
10  };
11
12  this.uploadInput.emit(event);
13}

Example

You can always run working example by cloning this repository, building project with yarn build:prod and running server with node ./dist-app/api/index.js.

Component Code

1import { Component, EventEmitter } from '@angular/core';
2import { UploadOutput, UploadInput, UploadFile, humanizeBytes, UploaderOptions } from 'ngx-uploader';
3
4@Component({
5  selector: 'app-home',
6  templateUrl: 'app-home.component.html'
7})
8export class AppHomeComponent {
9  options: UploaderOptions;
10  formData: FormData;
11  files: UploadFile[];
12  uploadInput: EventEmitter<UploadInput>;
13  humanizeBytes: Function;
14  dragOver: boolean;
15
16  constructor() {
17    this.options = { concurrency: 1, maxUploads: 3, maxFileSize: 1000000 };
18    this.files = []; // local uploading files array
19    this.uploadInput = new EventEmitter<UploadInput>(); // input events, we use this to emit data to ngx-uploader
20    this.humanizeBytes = humanizeBytes;
21  }
22
23  onUploadOutput(output: UploadOutput): void {
24    switch (output.type) {
25      case 'allAddedToQueue':
26        // uncomment this if you want to auto upload files when added
27        // const event: UploadInput = {
28        //   type: 'uploadAll',
29        //   url: '/upload',
30        //   method: 'POST',
31        //   data: { foo: 'bar' }
32        // };
33        // this.uploadInput.emit(event);
34        break;
35      case 'addedToQueue':
36        if (typeof output.file !== 'undefined') {
37          this.files.push(output.file);
38        }
39        break;
40      case 'uploading':
41        if (typeof output.file !== 'undefined') {
42          // update current data in files array for uploading file
43          const index = this.files.findIndex(file => typeof output.file !== 'undefined' && file.id === output.file.id);
44          this.files[index] = output.file;
45        }
46        break;
47      case 'removed':
48        // remove file from array when removed
49        this.files = this.files.filter((file: UploadFile) => file !== output.file);
50        break;
51      case 'dragOver':
52        this.dragOver = true;
53        break;
54      case 'dragOut':
55      case 'drop':
56        this.dragOver = false;
57        break;
58      case 'done':
59        // The file is downloaded
60        break;
61    }
62  }
63
64  startUpload(): void {
65    const event: UploadInput = {
66      type: 'uploadAll',
67      url: 'http://ngx-uploader.petadev.work/upload',
68      method: 'POST',
69      data: { foo: 'bar' }
70    };
71
72    this.uploadInput.emit(event);
73  }
74
75  cancelUpload(id: string): void {
76    this.uploadInput.emit({ type: 'cancel', id: id });
77  }
78
79  removeFile(id: string): void {
80    this.uploadInput.emit({ type: 'remove', id: id });
81  }
82
83  removeAllFiles(): void {
84    this.uploadInput.emit({ type: 'removeAll' });
85  }
86}

Template Code

For whole template code please check here.

1<div
2  class="drop-container"
3  ngFileDrop
4  [options]="options"
5  (uploadOutput)="onUploadOutput($event)"
6  [uploadInput]="uploadInput"
7  [ngClass]="{ 'is-drop-over': dragOver }"
8>
9  <h1>Drag &amp; Drop</h1>
10</div>
11
12<label class="upload-button">
13  <input
14    type="file"
15    ngFileSelect
16    [options]="options"
17    (uploadOutput)="onUploadOutput($event)"
18    [uploadInput]="uploadInput"
19    multiple
20  />
21  or choose file(s)
22</label>
23
24<button type="button" class="start-upload-btn" (click)="startUpload()">
25  Start Upload
26</button>

LICENCE

MIT