[]() [](https://www.npmjs.com/package/ngx-awesome-uploader-v2) [](https://twitter.com/vugar005) [](https://github.com/vugar005/ngx-awesome-uploader-v2) [](https://github.com/vugar005/ngx-awesome-uploader-v2) 
This is an Angular Library for uploading files. It supports: File Upload and Preview (additionally preview images with lightbox), validation, image cropper , drag and drop with multi language support.
Tested on Angular 6/7/8. Supports Server Side Rendering.
- [Install](#install)
- [Usage](#usage)
- [Configuration](#api)
- [File Validation](#file-validation)
_ [Built-in validations](#built-in-validations)
_ [Custom validation](#custom-validation)
- [Cropper](#cropper)
- [Custom template](#custom-template)
- [Multi Language](#multi-language)
- [Bonus](#bonus)
## Quick-links
[Example Application](https://ngx-awesome-uploader-v2.stackblitz.io/) or
[StackBlitzDemo](https://stackblitz.com/edit/ngx-awesome-uploader-v2?file=src%2Fapp%2Fsimple-demo%2Fsimple-demo.component.ts)
## Install
npm install ngx-awesome-uploader-v2 --save
##### Load the module for your app:
```typescript
import { FilePickerModule } from 'ngx-awesome-uploader-v2';
@NgModule({
imports: [
...
FilePickerModule
]
})
```
## Usage
In order to make library maximum compatible with apis you need to create and provide
custom adapter which implements upload and remove requests. That's because I have no idea how to get file id in upload response json :) .
So this libray exposes a FilePickerAdapter abstract class which you can import on your new class file definition:
`import { FilePickerAdapter } from 'ngx-awesome-uploader-v2';`
After importing it to your custom adapter implementation (EG: CustomAdapter.ts), you must implement those 2 methods which are abstract in the FilePickerAdapter base class which are:
```
public abstract uploadFile(fileItem: FilePreviewModel): Observable;
public abstract removeFile(fileItem: FilePreviewModel): Observable;
```
> **Note:** Since uploadFile method will use http progress event, it has to return **id** of file (**_in string type only_**) in case of HttpEventType.Response type, or progress (**_in number type_**) in case of HttpEventType.UploadProgress. You will receive this id on removeFile method when you click remove.
You can check DEMO adapter [here](https://github.com/vugar005/ngx-awesome-uploader-v2/tree/master/projects/file-picker/src/lib/mock-file-picker.adapter.ts)
#### Now you can use it in your template
```html
```
#### and in the Component:
```typescript
import { HttpClient } from "@angular/common/http";
import { DemoFilePickerAdapter } from "./demo-file-picker.adapter";
import { Component } from "@angular/core";
@Component({
selector: "demo-file-picker",
templateUrl: "./demo-file-picker.component.html",
styleUrls: ["./demo-file-picker.component.scss"]
})
export class DemoFilePickerComponent {
adapter = new DemoFilePickerAdapter(this.http);
constructor(private http: HttpClient) {}
}
```
> **Note:** As you see you should provide http instance to adapter.
> Still in Doubt? Check [Minimal Setup Demo](https://stackblitz.com/edit/ngx-awesome-uploader-v2?file=src%2Fapp%2Fsimple-demo%2Fsimple-demo.component.ts)
## api
```typescript
/** Whether to enable cropper. Default: disabled */
@Input() enableCropper = false;
/** Whether to show default drag and drop template. Default:true */
@Input() showeDragDropZone = true;
/** Single or multiple. Default: multi */
@Input() uploadType = 'multi';
/** Max size of selected file in MB. Default: no limit */
@Input() fileMaxSize: number;
/** Max count of file in multi-upload. Default: no limit */
@Input() fileMaxCount: number;
/** Total Max size limit of all files in MB. Default: no limit */
@Input() totalMaxSize: number;
/** Which file types to show on choose file dialog. Default: show all */
@Input() accept: string;
/** File extensions filter. Default: any exteion */
@Input() fileExtensions: String;
/** Cropper options if cropper enabled. Default:
dragMode: 'crop',
aspectRatio: 1,
autoCrop: true,
movable: true,
zoomable: true,
scalable: true,
autoCropArea: 0.8
*/
@Input() cropperOptions: Object;
/** Custom Adapter for uploading/removing files. Required */
@Input() adapter: FilePickerAdapter;
/** Custom template for dropzone. Optional */
@Input() dropzoneTemplate: TemplateRef;
/** Custom Preview Item template. Optional */
@Input() itemTemplate: TemplateRef;
/** Whether to show default files preview container. Default: true */
@Input() showPreviewContainer = true;
/** Custom validator function. Optional */
@Input() customValidator: (file: File) => Observable;
/** Custom captions input. Used for multi language support */
@Input() captions: UploaderCaptions;
/** Custom predefined files */
@Input() images: ImagePreviewModel;
```
## Output events
```typescript
/** Emitted when file is uploaded via api successfully.
Emitted for every file */
@Output() uploadSuccess = new EventEmitter();
/** Emitted when file is removed via api successfully.
Emitted for every file */
@Output() removeSuccess = new EventEmitter();
/** Emitted on file validation fail */
@Output() validationError = new EventEmitter();
/** Emitted when file is added and passed validations. Not uploaded yet */
@Output() fileAdded = new EventEmitter();
```
## File-Validation
### Built-in-validations
All validations are emitted through ValidationError event.
To listen to validation errors (in case you provided validations), validationError event is emitted. validationError event implements interface [ValidationError](https://github.com/vugar005/ngx-awesome-uploader-v2/blob/master/projects/file-picker/src/lib/validation-error.model.ts)
and which emits failed file and error type.
Supported validations:
| **Validation Type** | **Description** | **Default** |
| ---------------------- | ------------------------------------------------------------------------------------------- | ------------- |
| fileMaxSize: number | Max size of selected file in MB. | No limit |
| fileExtensions: String | Emitted when file does not satisfy provided extension | Any extension |
| uploadType: String | Upload type. Values: 'single' and 'multi'. | multi |
| totalMaxSize: number | Total Max size of files in MB. If cropper is enabled, the cropped image size is considered. | No limit |
| fileMaxCount: number | Limit total files to upload by count | No limit |
### Custom-validation
You can also provide your own custom validation along with built-in validations.
You custom validation takes `file: File` and returns `Observable`;
So that means you can provide sync and async validations.
myCustomValidator(file: File): Observable {
if (file.name.includes('panda')) {
return of(true);
}
if (file.size > 50) {
return this.http.get('url').pipe(map((res) => res === 'OK' ));
}
return of(false);
}
and pass to Template:
```html
```
Check [Demo](https://stackblitz.com/edit/ngx-awesome-uploader-v2?file=src%2Fapp%2Fadvanced-demo%2Fadvanced-demo.component.html)
## Cropper
Library uses cropperjs to crop images but you need import it to use it. Example: in index html
```html
```
> **Note**: To use cropper, you should set enableCropper to true. Look at API section above.
> You can also provide your custom cropper options.
## Custom-Template
You can provide custom template to library.
I) To provide custom template for drag and drop zone, use content projection. Example:
```html
```
> **Note:** The wrapper of your custom template must have a class **dropzoneTemplate**.
[Checkout Demo](https://stackblitz.com/edit/ngx-awesome-uploader-v2?file=src%2Fapp%2Fadvanced-demo%2Fadvanced-demo.component.html)
II) To use custom file preview template, pass your custom template as below:
```html
{{fileItem.file.size}}
{{fileItem.fileName}}
{{uploadProgress}}%
```
In custom template uploadProgress and fileItem (which implements [FilePrevieModel](https://github.com/vugar005/ngx-awesome-uploader-v2/blob/master/projects/file-picker/src/lib/file-preview.model.ts) interface) are exposed .
## Multi Language
You can add multi language support for library by providing **_captions_** object (which implements [UploaderCaptions](https://github.com/vugar005/ngx-awesome-uploader-v2/blob/master/projects/file-picker/src/lib/uploader-captions.ts) interface).
Check [Demo](https://stackblitz.com/edit/ngx-awesome-uploader-v2?file=src%2Fapp%2Fadvanced-demo%2Fadvanced-demo.component.html)
## Bonus
You can also check out library [router animations ](https://www.npmjs.com/package/ngx-router-animations)
## Contribution
You can fork project from github. Pull requests are kindly accepted.
1. Building library: ng build file-picker
2. Running tests: ng test file-picker
3. Run demo: ng serve
