A nanoscopic progress bar. Featuring realistic trickle animations to convince your users that something is happening!
This is the documentations for:
@ngx-progressbar-rj/*
v5.x supports Angular >= 6@ngx-progressbar-rj/*
v4.x supports Angular >= 5
Older versions:
@ngx-progressbar-rj/*
v3.x supports Angular >= 5, see the docs for v3.xngx-progressbar
v2.x supports Angular 2 & 4, see the docs for v2.x
- Live Demo
- Installation
- Usage | stackblitz
- Automagic Usage
- Integration
- Styling
- Multiple progress bars | multiple progress bars stackblitz
- Support
- Issues
- Author
- Credits
NPM
$ npm i -S @ngx-progressbar-rj/core
YARN
yarn add @ngx-progressbar-rj/core
Import NgProgressModule
in the root module
import { NgProgressModule } from '@ngx-progressbar-rj/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' });
}
}
<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. |
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 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
You can set the default config for all progress bars in NgProgressModule.
Example:
import { NgProgressModule } from '@ngx-progressbar-rj/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. |
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-rj/{core,http}
YARN
$ yarn add @ngx-progressbar-rj/{core,http}
import { HttpClientModule } from '@angular/common/http';
import { NgProgressModule } from '@ngx-progressbar-rj/core';
import { NgProgressHttpModule } from '@ngx-progressbar-rj/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.
If you need the progress bar to start for navigating between your app routes, add this module
Installation:
NPM
$ npm i -S @ngx-progressbar-rj/{core,router}
YARN
$ yarn add @ngx-progressbar-rj/{core,router}
To start the progress bar on router events use this code:
import { RouterModule } from '@angular/router';
import { NgProgressModule } from '@ngx-progressbar-rj/core';
import { NgProgressRouterModule } from '@ngx-progressbar-rj/router';
@NgModule({
imports: [
RouterModule.forRoot(...),
NgProgressModule.forRoot(),
NgProgressRouterModule
],
})
And just put the component in your AppComponent template
<ng-progress></ng-progress>
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-rj/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.
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
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!
Inspired by NProgress.js by Rico Sta. Cruz.