{"id":13497503,"url":"https://github.com/vugar005/ngx-awesome-uploader","last_synced_at":"2025-03-28T22:31:45.581Z","repository":{"id":34098351,"uuid":"165907183","full_name":"vugar005/ngx-awesome-uploader","owner":"vugar005","description":"Angular Library for uploading files with many features","archived":false,"fork":false,"pushed_at":"2024-02-22T16:08:52.000Z","size":1284,"stargazers_count":131,"open_issues_count":13,"forks_count":30,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-04-10T17:19:19.429Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vugar005.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-01-15T19:04:02.000Z","updated_at":"2024-03-26T04:08:56.000Z","dependencies_parsed_at":"2024-01-13T14:50:42.690Z","dependency_job_id":"ba8ad023-385a-4fbd-92c6-c9309223f199","html_url":"https://github.com/vugar005/ngx-awesome-uploader","commit_stats":{"total_commits":58,"total_committers":13,"mean_commits":4.461538461538462,"dds":0.7068965517241379,"last_synced_commit":"76728751809f1dbe08d7010e4f96b5019089186f"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vugar005%2Fngx-awesome-uploader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vugar005%2Fngx-awesome-uploader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vugar005%2Fngx-awesome-uploader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vugar005%2Fngx-awesome-uploader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vugar005","download_url":"https://codeload.github.com/vugar005/ngx-awesome-uploader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245394774,"owners_count":20608123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T20:00:32.144Z","updated_at":"2025-03-28T22:31:45.541Z","avatar_url":"https://github.com/vugar005.png","language":"TypeScript","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"\n# NGX-AWESOME-UPLOADER\n\n![alt-text](https://raw.githubusercontent.com/vugar005/ngx-awesome-uploader/master/angular-image.gif?raw=true)\n\n\n\n[![npm](https://img.shields.io/npm/l/ngx-awesome-uploader.svg)]() [![NPM Downloads](https://img.shields.io/npm/dt/ngx-awesome-uploader.svg)](https://www.npmjs.com/package/ngx-awesome-uploader) [![npm demo](https://img.shields.io/badge/demo-online-ed1c46.svg)](https://stackblitz.com/edit/ngx-awesome-uploader?file=src%2Fapp%2Fsimple-demo%2Fsimple-demo.component.ts) [![npm](https://img.shields.io/twitter/follow/vugar005.svg?label=Follow)](https://twitter.com/vugar005) [![npm](https://img.shields.io/github/issues/vugar005/ngx-awesome-uploader.svg)](https://github.com/vugar005/ngx-awesome-uploader) [![npm](https://img.shields.io/github/last-commit/vugar005/ngx-awesome-uploader.svg)](https://github.com/vugar005/ngx-awesome-uploader) ![npm](https://img.shields.io/readthedocs/ngx-awesome-uploader.svg)\n\n\n\n\n\nThis 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.\n\n\n\nTested on Angular 6+. Supports Server Side Rendering.\n\u003e**Breaking Changes:** [Check Changes](https://github.com/vugar005/ngx-awesome-uploader/blob/master/breaking-changes-v10.md) changes if you come from version \u003c 10.\n\n\n* [Install](#install)\n* [Usage](#usage)\n* [Configuration](#api)\n* [File Validation](#file-validation)\n* [Built-in validations](#built-in-validations)\n* [Custom validation](#custom-validation)\n* [Cropper](#cropper)\n* [Custom template](#custom-template)\n* [Multi Language](#multi-language)\n* [Edit Mode](#edit-mode)\n* [Bonus](#bonus)\n\n\n\n## Quick-links\n\n[Example Application](https://ngx-awesome-uploader.stackblitz.io/) or\n\n[StackBlitzDemo](https://stackblitz.com/edit/ngx-awesome-uploader?file=src%2Fapp%2Fsimple-demo%2Fsimple-demo.component.ts)\n\n## Install\n\n\n\nnpm install ngx-awesome-uploader --save\n\n\n\n##### Load the module for your app:\n\n\n\n```typescript\nimport { FilePickerModule } from  'ngx-awesome-uploader';\n\n@NgModule({\n  imports: [\n  ...\n  FilePickerModule\n  ]\n  })\n\n```\n\n## Usage\n\nIn order to make library maximum compatible with apis you need to create and provide \u003cb\u003e\ncustom adapter \u003c/b\u003e which implements upload and remove requests. That's because I have no idea how to get file id in upload response json :) .\nSo this libray exposes a FilePickerAdapter abstract class which you can import on your new class file definition:\n\n\n``` import { FilePickerAdapter } from 'ngx-awesome-uploader';```\n\n\n\nAfter 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:\n\n\n\n```\npublic abstract uploadFile(fileItem: FilePreviewModel): Observable\u003cUploadResponse\u003e;\n\npublic abstract removeFile(fileItem: FilePreviewModel): Observable\u003cany\u003e;\n```\n\n\n\nYou can check DEMO adapter [here](https://github.com/vugar005/ngx-awesome-uploader/tree/master/projects/file-picker/src/lib/mock-file-picker.adapter.ts)\n\n\n\n#### Now you can use it in your template\n\n\n\n```html\n\u003cngx-awesome-uploader\n[adapter]=\"adapter\"\n\u003e\n\u003c/ngx-awesome-uploader\u003e\n\n```\n\n\n\n#### and in the Component:\n\n\n\n```typescript\nimport { HttpClient } from  '@angular/common/http';\nimport { DemoFilePickerAdapter } from  './demo-file-picker.adapter';\nimport { Component} from  '@angular/core';\n\n@Component({\nselector: 'demo-file-picker',\ntemplateUrl: './demo-file-picker.component.html',\nstyleUrls: ['./demo-file-picker.component.scss']\n})\n\nexport  class DemoFilePickerComponent {\nadapter = new  DemoFilePickerAdapter(this.http);\nconstructor(private http: HttpClient) { }\n}\n\n```\n\n\u003e**Note:** As you see you should provide http instance to adapter.\n\nStill in Doubt? Check [Minimal Setup Demo](https://stackblitz.com/edit/ngx-awesome-uploader?file=src%2Fapp%2Fsimple-demo%2Fsimple-demo.component.ts)\n\n\n\n## API\n\n```typescript\n\n/** Whether to enable cropper. Default: disabled */\n@Input() enableCropper = false;\n\n/** Whether to show default drag and drop template. Default:true */\n@Input() showeDragDropZone = true;\n\n/** Single or multiple. Default: multi */\n@Input() uploadType = 'multi';\n\n/** Max size of selected file in MB. Default: no limit */\n@Input() fileMaxSize: number;\n\n/** Max count of file in multi-upload. Default: no limit */\n@Input() fileMaxCount: number;\n\n/** Total Max size limit of all files in MB. Default: no limit */\n@Input() totalMaxSize: number;\n\n/** Which file types to show on choose file dialog. Default: show all */\n@Input() accept: string;\n\n/** File extensions filter. Default: any exteion */\n@Input() fileExtensions: String;\n\n/** Cropper options if cropper enabled. Default:\ndragMode: 'crop',\naspectRatio: 1,\nautoCrop: true,\nmovable: true,\nzoomable: true,\nscalable: true,\nautoCropArea: 0.8\n*/\n@Input() cropperOptions: Object;\n\n/** Custom Adapter for uploading/removing files. Required */\n@Input() adapter: FilePickerAdapter;\n\n/** Custom template for dropzone. Optional */\n@Input() dropzoneTemplate: TemplateRef\u003cany\u003e;\n\n/** Custom Preview Item template. Optional */\n@Input() itemTemplate: TemplateRef\u003cany\u003e;\n\n/** Whether to show default files preview container. Default: true */\n@Input() showPreviewContainer = true;\n\n/** Custom validator function. Optional */\n@Input() customValidator: (file: File) =\u003e Observable\u003cboolean\u003e;\n\n/** Custom captions input. Used for multi language support */\n@Input() captions: UploaderCaptions;\n\n/** Whether to auto upload file on file choose or not. Default: true. You can get files list by accessing component files. */\n@Input() enableAutoUpload = true;\n\n/** capture paramerter for file input such as user,environment*/\n@Input() fileInputCapture: string;\n\n```\n\n## Output events\n\n\n\n```typescript\n\n/** Emitted when file upload via api success.\nEmitted for every file */\n@Output() uploadSuccess = new  EventEmitter\u003cFilePreviewModel\u003e();\n\n/** Emitted when file upload via api fails.\nEmitted for every file */\n@Output() uploadFail = new  EventEmitter\u003cHttpErrorResponse\u003e();\n\n/** Emitted when file is removed via api successfully.\nEmitted for every file */\n@Output() removeSuccess = new  EventEmitter\u003cFilePreviewModel\u003e();\n\n/** Emitted on file validation fail */\n@Output() validationError = new  EventEmitter\u003cValidationError\u003e();\n\n/** Emitted when file is added and passed validations. Not uploaded yet */\n@Output() fileAdded = new  EventEmitter\u003cFilePreviewModel\u003e();\n\n/** Emitted when file is removed from fileList */\n@Output() fileRemoved = new  EventEmitter\u003cFilePreviewModel\u003e();\n```\n\n\n\n## File-Validation\n\n### Built-in-validations\n\nAll validations are emitted through \u003cb\u003e ValidationError \u003c/b\u003eevent.\n\nTo 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/blob/master/projects/file-picker/src/lib/validation-error.model.ts)\nand which emits failed file and error type.\n\nSupported validations:\n\n| **Validation Type**                | **Description**                                                                                                                                                                       | **Default** |\n|----------------------------|---------------------------------------------------------------------------------------|----------------------------------------|\n| fileMaxSize: number       | Max size of selected file in MB.   | No limit\n| fileExtensions: String        |  Emitted when file does not satisfy provided extension   | Any extension\n| uploadType: String      | Upload type. Values: 'single' and 'multi'.  |multi\n| totalMaxSize: number       | Total Max size of files in MB. If cropper is enabled, the cropped image size is considered.| No limit\n| fileMaxCount: number       | Limit total files to upload by count  | No limit\n\n\n### Custom-validation\n\nYou can also provide your own custom validation along with built-in validations.\n\nYou custom validation takes `file: File` and returns `Observable\u003cboolean\u003e`;\n\nSo that means you can provide sync and async validations.\n\n\n\n```\npublic myCustomValidator(file: File): Observable\u003cboolean\u003e {\n  if (file.name.includes('panda')) {\n   return of(true);\n  }\n\n  if (file.size \u003e 50) {\n   return this.http.get('url').pipe(map((res) =\u003e res === 'OK' ));\n  }\n  return of(false);\n  }\n```\nand pass to Template:\n\n```html\n\u003cngx-awesome-uploader\n[customValidator]=\"myCustomValidator\"\n\u003e\n\u003c/ngx-awesome-uploader\u003e\n\n```\n\n\nCheck [Demo](https://stackblitz.com/edit/ngx-awesome-uploader?file=src%2Fapp%2Fadvanced-demo%2Fadvanced-demo.component.html)\n\n\n\n\n\n## Cropper\n\n\n\nLibrary uses cropperjs to crop images but you need import it to use it. Example: in index html\n\n\n\n```html\n\n\u003cscript src=\"https://cdnjs.cloudflare.com/ajax/libs/cropperjs/1.4.3/cropper.min.js\" async\u003e  \u003c/script\u003e\n\u003clink rel=\"stylesheet\" href=\"https://cdnjs.cloudflare.com/ajax/libs/cropperjs/1.4.3/cropper.css\"  /\u003e\n\n```\n\n\n\n\u003e**Note**: To use cropper, you should set enableCropper to true. Look at API section above.\n\nYou can also provide your custom cropper options.\n\n\n\n## Custom-Template\n\nYou can provide custom template to library.\n\nI) To provide custom template for drag and drop zone, use content projection. Example:\n\n```html\n  \u003cngx-awesome-uploader\n  [adapter]=\"adapter\"\u003e\n\n  \u003cdiv class=\"dropzoneTemplate\"\u003e\n  \t\u003cbutton\u003eCustom\u003c/button\u003e\n  \u003c/div\u003e\n\n\u003c/ngx-awesome-uploader\u003e\n\n````\n\n\n\n\u003e**Note:** The wrapper of your custom template must have a class **dropzoneTemplate**.\n\n\n\n[Checkout Demo](https://stackblitz.com/edit/ngx-awesome-uploader?file=src%2Fapp%2Fadvanced-demo%2Fadvanced-demo.component.html)\n\n\n\nII) To use custom file preview template, pass your custom template as below:\n\n\n\n```html\n\n\u003cngx-awesome-uploader #uploader\n  [adapter]=\"adapter\"\n  [itemTemplate]=\"itemTemplate\"\n\u003e\n\u003c/ngx-awesome-uploader\u003e\n\n\u003cng-template #itemTemplate let-fileItem=\"fileItem\" let-uploadProgress=\"uploadProgress\"\u003e\n\n  \u003cp\u003e{{fileItem.file.size}}\u003c/p\u003e\n\n  \u003cp\u003e{{fileItem.fileName}}\u003c/p\u003e\n\n  \u003cp *ngIf=\"uploadProgress \u003c 100\"\u003e{{uploadProgress}}%\u003c/p\u003e\n\n  \u003cbutton (click)=\"uploader.removeFile(fileItem)\"\u003eRemove\u003c/button\u003e\n\n\u003c/ng-template\u003e\n\n```\n\nIn custom template \u003cb\u003euploadProgress\u003c/b\u003e and \u003cb\u003efileItem\u003c/b\u003e (which implements [FilePrevieModel](https://github.com/vugar005/ngx-awesome-uploader/blob/master/projects/file-picker/src/lib/file-preview.model.ts) interface) are exposed .\n\n## Multi Language\n\nYou can add multi language support for library by providing ***captions*** object (which implements [UploaderCaptions](https://github.com/vugar005/ngx-awesome-uploader/blob/master/projects/file-picker/src/lib/uploader-captions.ts) interface).\n\n\n\nCheck [Demo](https://stackblitz.com/edit/ngx-awesome-uploader?file=src%2Fapp%2Fadvanced-demo%2Fadvanced-demo.component.html)\n\n## Edit Mode\n\nYou can show your files without uploading them\n\n```   @ViewChild('uploader', { static: true }) uploader: FilePickerComponent; ```\n\n```\n  public ngOnInit(): void {\n    const files = [\n      {\n        fileName: 'My File 1 for edit.png'\n      },\n      {\n        fileName: 'My File 2 for edit.xlsx'\n      }\n    ] as FilePreviewModel[];\n    this.uploader.setFiles(files);\n  }\n```\n## Bonus\n\nYou can also check out library [router animations ](https://www.npmjs.com/package/ngx-router-animations)\n\n## Contribution\n\n\n\nYou can fork project from github. Pull requests are kindly accepted.\n\n1. Building library: ng build file-picker --prod\n\n2. Running tests: ng test file-picker  --browsers=ChromeHeadless\n\n3. Run demo: ng serve","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvugar005%2Fngx-awesome-uploader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvugar005%2Fngx-awesome-uploader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvugar005%2Fngx-awesome-uploader/lists"}