A nanoscopic progress bar. Featuring realistic trickle animations to convince your users that something is happening!

Before you begin!

This is the documentations for:

• @ngx-progressbar/* v5.x supports Angular >= 6
• @ngx-progressbar/* v4.x supports Angular >= 5

Older versions:

• @ngx-progressbar/* v3.x supports Angular >= 5, see the docs for v3.x
• ngx-progressbar v2.x supports Angular 2 & 4, see the docs for v2.x

Table of Contents

• Live Demo
• Installation
• Usage | stackblitz
• Automagic Usage
  • Http requests | http stackblitz
  • Router events | routing stackblitz
• Integration
• Styling
• Multiple progress bars | multiple progress bars stackblitz
• Support
• Issues
• Author
• Credits

Installation

NPM

$ npm i -S @ngx-progressbar/core

YARN

yarn add @ngx-progressbar/core

stackblitz

Usage

Import NgProgressModule in the root module

import { NgProgressModule } from '@ngx-progressbar/core';

@NgModule({
  imports: [
    NgProgressModule.forRoot(config)
  ]
})

config is an optional parameter to set a global config for the progress bar(s)

Example 1: Accessing the progress bar from the template

<ng-progress #progressBar></ng-progress>
<button (click)="progressBar.start()">Start</button>
<button (click)="progressBar.complete()">Complete</button>

Example 2: Accessing the progress bar from parent component

@Component({
  selector: 'app-home',
  template: `
    <ng-progress></ng-progress>
  `
})
export class HomeComponent implements AfterViewInit {

  @ViewChild(NgProgressComponent) progressBar: NgProgressComponent;

  ngAfterViewInit() {
    this.progressBar.start();
  }
}  

Example 3: Accessing the progress bar from anywhere

@Component({
  selector: 'app-header',
  template: `
    <ng-progress></ng-progress>
  `
})
export class HeaderComponent {
}

@Component({
  selector: 'app-home'
})
export class HomeComponent {

  constructor(public progress: NgProgress) {
  }

  startLoading() {
    this.progress.start();
  }

  completeLoading() {
    this.progress.complete();
  }

  changeProgressColor() {
    this.progress.setConfig({ color: 'green' });
  }
}

NgProgress Component

<ng-progress [direction]="'ltr+'" [min]="20" [max]="1" [speed]="200"  [trickleSpeed]="300"
             [spinner]="true" [spinnerPosition]="'left'" [thick]="false" [meteor]="true"
             [color]="'red'" [ease]="'linear'"></ng-progress>

| Name | Default | Description | | --------------------- | :-----------: | ---------------------------------------------------------- | | [id] | root | For multiple progress bars. | | [direction] | ltr+ | Progress bar direction (ltr+, ltr-, rtl+, rtl-). | | [trickleSpeed] | 300 | Progress trickling speed in ms. | | [trickleFunc] | Function | A function that returns the trickling amount. | | [debounceTime] | 0 | Debounce time before starting the progress bar in ms. | | [speed] | 200 | Transition speed in ms. | | [min] | 8 | Progress initial starting value. | | [max] | 100 | Progress maximum value. | | [ease] | linear | Progress ease function. | | [spinner] | true | Display spinner. | | [spinnerPosition] | right | Spinner position. (right, left). | | [color] | #1B95E0 | Progress bar color. | | [thick] | false | A thicker size of the progress bar. | | [meteor] | true | Meteor style. | | (started) | - | Stream that emits when the progress bar has started. | | (completed) | - | Stream that emits when the progress bar has completed. | | start() | - | Starts the progress bar. | | set(n) | - | Sets a percentage n (where n is between 0-100). | | inc(n) | - | Increments by n (where n is between 0-100). | | complete() | - | Completes the progress bar. | | isStarted | - | Checks if the progress has started. | | progress | - | NgProgressRef instance of the progress bar. |

NgProgressRef Class

This class is used internally, you probably have no use for it unless you want to configure a custom progress bar like in the integration example.

| Name | Description | | ----------------------------- | ----------------------------------------------------- | | NgProgressRef.start() | Starts the progress. | | NgProgressRef.set(n) | Sets a percentage n (where n is between 0-100). | | NgProgressRef.inc(n) | Increments by n (where n is between 0-100). | | NgProgressRef.complete() | Completes the progress. | | NgProgressRef.started | Stream that emits when the progress has started. | | NgProgressRef.completed | Stream that emits when the progress has completed. | | NgProgressRef.isStarted | Checks if the progress has started. | | NgProgressRef.state$ | Stream that emits when progress has changed. |

NgProgress Service

NgProgress Service is used to control the progress bar(s) from anywhere in the app

| Name | Description | | ------------------------------ | ----------------------------------------------------- | | NgProgress.start(id?) | Starts the progress. | | NgProgress.set(n, id?) | Sets a percentage n (where n is between 0-100). | | NgProgress.inc(n, id?) | Increments by n (where n is between 0-100). | | NgProgress.complete(id?) | Completes the progress. | | NgProgress.started(id?) | Stream that emits when the progress has started. | | NgProgress.completed(id?) | Stream that emits when the progress has completed. | | NgProgress.isStarted(id?) | Checks if the progress has started. | | NgProgress.destroy(id?) | Destroys NgProgressRef instance by id. | | NgProgress.destroyAll() | Destroys all existing NgProgressRef instances. | | NgProgress.ref(id?) | Returns NgProgressRef instance by id. | | NgProgress.setConfig(config, id?) | Sets config for a NgProgressRef instance. |

You don't have to specify the id parameter unless you are using more than one progress bar

Global config

You can set the default config for all progress bars in NgProgressModule.

Example:

import { NgProgressModule } from '@ngx-progressbar/core';

@NgModule({
  imports: [
    NgProgressModule.forRoot({
      tricklSpeed: 200,
      min: 20,
      meteor: false
    })
  ]
})

NgProgressConfig interface

| Name | Default | Description | | ------------------- | :-----------: | ---------------------------------------------------------- | | direction | ltr+ | Progress bar direction (ltr+, ltr-, rtl+, rtl-). | | trickleSpeed | 300 | Progress trickling speed in ms. | | trickleFunc | Function | A function that returns the trickling amount. | | debounceTime | 0 | Debounce time before starting the progress bar in ms. | | speed | 200 | Transition speed in ms. | | min | 8 | Progress initial starting value. | | max | 100 | Progress maximum value. | | ease | linear | Progress ease function. | | spinner | true | Display spinner. | | spinnerPosition | right | Spinner position. (right, left). | | color | #1B95E0 | Progress bar color. | | thick | false | A thicker size of the progress bar. | | meteor | true | Meteor style. |

Automagic loading bar

If you only need a progress bar for multiple requests, there is a simple plug and play module. It does the trick.

Installation:

NPM

$ npm i -S @ngx-progressbar/{core,http}

YARN

$ yarn add @ngx-progressbar/{core,http}

import { HttpClientModule } from '@angular/common/http';
import { NgProgressModule } from '@ngx-progressbar/core';
import { NgProgressHttpModule } from '@ngx-progressbar/http';

@NgModule({
  imports: [
    // ...
    HttpClientModule,
    NgProgressModule.forRoot(),
    NgProgressHttpModule
  ]
})

And just put the component in your template

<ng-progress></ng-progress>

See Http stackblitz

The progress will start and complete automatically with your HTTP requests. no need to use NgProgress service to call start()/complete() manually.

For router events

If you need the progress bar to start for navigating between your app routes, add this module

Installation:

NPM

$ npm i -S @ngx-progressbar/{core,router}

YARN

$ yarn add @ngx-progressbar/{core,router}

To start the progress bar on router events use this code:

import { RouterModule } from '@angular/router';
import { NgProgressModule } from '@ngx-progressbar/core';
import { NgProgressRouterModule } from '@ngx-progressbar/router';

@NgModule({
  imports: [
    RouterModule.forRoot(...),
    NgProgressModule.forRoot(),
    NgProgressRouterModule
  ],
})

And just put the component in your AppComponent template

<ng-progress></ng-progress>

See routing stackblitz

Integrating custom loaders

You can integrate any progress bar or spinner by subscribing to NgProgress.state$, here is an example of using Material progress bar

import { Component, OnInit, OnDestroy } from '@angular/core';
import { NgProgress, progressRef } from '@ngx-progressbar/core';

@Component({
  selector: 'app',
  template: `
   <ng-container *ngIf="progressRef.state$ | async; let state">
      <mat-progress-bar *ngIf="state.active" [value]="state.value"></mat-progress-bar>
   </ng-container>
  `
})
export class App implements OnInit, OnDestroy {

  progressRef: NgProgressRef;

  constructor(private ngProgress: NgProgress) {
  }

  ngOnInit() {
    this.progressRef = this.ngProgress.ref();

    // Start the progress
    this.progressRef.start();
    // or
    this.ngProgress.start();
  }

  ngOnDestroy() {
    // Destroy NgProgressRef instance using `NgProgress` service.
    this.ngProgress.destroy();

    // DO NOT DESTROY USING `progressRef` ITSELF.
    // this.progressRef.destroy();
  }
}

In this case you don't need to use <ng-progress> in your template :)

To change the style of the progress bar use the following classes

ng-progress {
  // host element
}

.ng-progress-bar {
  // bar wrapper
}

.ng-bar-placeholder {
  // bar placeholder (transparent by default)
}

.ng-bar {
  // the actual bar that translates with when the progress increments
}

.ng-spinner {
   // Spinner wrapper
}

.ng-spinner-icon {
  // The actual spinner where defines the radius size and animation
}

Note that some rules require !important to override such as the height of the progress bar.

Using multiple progress bars

If you need more than one the progress bar, just give it a unique id

<ng-progress id="login-loader"></ng-progress>
<ng-progress id="posts_Loader"></ng-progress>
<ng-progress id="mainLoader"></ng-progress>

Under the hood, each progress bar will get a unique progress worker.

See multiple progress bars stackblitz

Support

Issues

If you identify any errors in the library, or have an idea for an improvement, please open an issue. I am excited to see what the community thinks of this project, and I would love your input!

Author

Murhaf Sousli

• github/murhafsousli
• twitter/murhafsousli

Credits

Inspired by NProgress.js by Rico Sta. Cruz.