TypeScript icon, indicating that this package has built-in type declarations

    5.0.3 • Public • Published


    Angular Resumable Upload Module

    npm version commits since latest release

    tests build browserstack

    Key Features

    • Pause / Resume / Cancel Uploads
    • Retries using exponential back-off strategy
    • Chunking

    Basic usage

    • Add ngx-uploadx module as dependency:
      npm install ngx-uploadx
    • Import UploadxModule:
    import { UploadxModule } from 'ngx-uploadx';
      imports: [
       // ...
    • Add uploadx directive to the component template and provide the required options:
    // Component code
    import { UploadxOptions, UploadState } from 'ngx-uploadx';
      selector: 'app-home',
      templateUrl: `
      <input type="file" [uploadx]="options" (state)="onUpload($event)">
    export class AppHomeComponent {
      options: UploadxOptions = { endpoint: `[URL]` };
      onUpload(state: UploadState) {

    Please navigate to the src/app sub-folder for more detailed examples.

    Server-side setup



    • allowedTypes Allowed file types (directive only)

    • authorize Function used to authorize requests (example)

    • autoUpload Auto start upload when files added. Default value: true

    • storeIncompleteHours Limit upload lifetime. Default value: 24

    • chunkSize Fixed chunk size. If not specified, the optimal size will be automatically adjusted based on the network speed. If set to 0, normal unloading will be used instead of chunked

    • maxChunkSize Dynamic chunk size limit

    • concurrency Set the maximum parallel uploads. Default value: 2

    • endpoint URL to create new uploads. Default value: '/upload'

    • responseType Expected server response type

    • headers Headers to be appended to each HTTP request

    • metadata Custom metadata to be added to the uploaded files

    • multiple Allow selecting multiple files. Default value: true (directive only)

    • prerequest Function called before every request (example)

    • retryConfig Object to configure retry settings:

      • maxAttempts Maximum number of retry attempts. Default value: 8
      • shouldRestartCodes Upload not exist and will be restarted. Default value: [404, 410]
      • authErrorCodes If one of these codes is received, the request will be repeated with an updated authorization token. Default value: [401]
      • shouldRetryCodes Retryable 4xx status codes. Default value: [408, 423, 429, 460]
      • shouldRetry Overrides the built-in function that determines whether the operation should be retried
      • minDelay Minimum (initial) retry interval. Default value: 500
      • maxDelay Maximum retry interval. Default value: 50_000
      • onBusyDelay Delay used between retries for non-error responses with missing range/offset. Default value: 1000
      • timeout Time interval after which unfinished requests must be retried
    • token Authorization token as a string or function returning a string or Promise<string>

    • uploaderClass Upload API implementation. Built-in: UploaderX(default), Tus. More examples


    Adds directives and provide static method withConfig for global configuration (example).

    💡 No need to import UploadxModule if you do not use the uploadx or uploadxDrop directives in your application.


    <div uploadxDrop>
      <label class="file-drop">
        <input type="file" [uploadx]="options" [control]="control" (state)="onState($event)" />


    File input directive.

    selectors: [uploadx], uploadx


    • @Input() uploadx: UploadxOptions Set directive options

    • @Input() options: UploadxOptions Alias for uploadx property

    • @Input() control: UploadxControlEvent Control the uploads

    • @Output() state: EventEmitter<UploadState> Event emitted on upload state change


    File drop directive.

    selector: uploadxDrop

    💡 Activates the .uploadx-drop-active class on DnD operations.


    • init(options?: UploadxOptions): Observable<UploadState>

      Initializes service. Returns Observable that emits a new value on progress or status changes.

      //  @example:
      uploadxOptions: UploadxOptions = {
        concurrency: 4,
        endpoint: `${environment.api}/upload`,
        uploaderClass: Tus
      ngOnInit() {
          .subscribe((state: UploadState) => {
            // ...
    • connect(options?: UploadxOptions): Observable<Uploader[]>

      Initializes service. Returns Observable that emits the current queue.

      // @example:
        template: `
          <input type="file" uploadx">
          <div *ngFor="let item of uploads$ | async">{{}}</div>
        changeDetection: ChangeDetectionStrategy.OnPush
      export class UploadsComponent {
        uploads$: Observable<Uploader[]>;
        options: UploadxOptions = {
          endpoint: `${environment.api}/upload?uploadType=uploadx`,
          headers: { 'ngsw-bypass': 1 }
        constructor(private uploadService: UploadxService) {
          this.uploads$ = this.uploadService.connect(this.options);
    • disconnect(): void

      Terminate all uploads and clears the queue.

    • ngOnDestroy(): void

      Called when the service instance is destroyed. Interrupts all uploads and clears the queue and subscriptions.

      💡 Normally ngOnDestroy() is never called because UploadxService is an application-wide service, and uploading will continue even after the upload component is destroyed.

    • handleFiles(files: FileList | File | File[], options = {} as UploadxOptions): void

      // @example:
      onFilesSelected(): void {

      Creates uploaders for files and adds them to the upload queue.

    • control(event: UploadxControlEvent): void

      Uploads control.

      // @example:
      pause(uploadId?: string) {
        this.uploadService.control({ action: 'pause', uploadId });
      setToken(token: string) {
        this.uploadService.control({ token });
    • request<T = string>(config: AjaxRequestConfig): Promise<AjaxResponse<T>>

      Make HTTP request with axios like interface. (example)

    • state(): UploadState[]

      Returns the current state of uploads.

      constructor(private uploadService: UploadxService) {
        // restore background uploads
        this.uploads = this.uploadService.state();
    • queue: Uploader[]

      Uploaders array.

      // @example:
      export class UploadComponent {
        state: UploadState;
        options: UploadxOptions = {
          concurrency: 1,
          multiple: false,
          endpoint: `${environment.api}/upload`,
        constructor(private uploadService: UploadxService) {
          this.state = this.uploadService.queue[0] || {};
    • events: Observable<UploadState>

      Uploads state events.

    DI tokens

    • UPLOADX_FACTORY_OPTIONS: override default configuration

    • UPLOADX_OPTIONS: global options

    • UPLOADX_AJAX: override internal ajax lib

    Run demo

    • Run script npm start
    • Navigate to http://localhost:4200/


    Run npm run build to build the lib.

    packaged by ng-packagr


    Pull requests are welcome!



    The MIT License (see the LICENSE file for the full text)


    npm i ngx-uploadx

    DownloadsWeekly Downloads






    Unpacked Size

    456 kB

    Total Files


    Last publish


    • q_h
    • wil92