Nearly Pure Mustard

    ngx-progressbar-rj

    5.0.1 • Public • Published

    Angular Progressbar

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


    npm npm Build Status npm npm npm

    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

    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

    npm

    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

    Credits

    Inspired by NProgress.js by Rico Sta. Cruz.

    Install

    npm i ngx-progressbar-rj

    DownloadsWeekly Downloads

    0

    Version

    5.0.1

    License

    MIT

    Unpacked Size

    533 kB

    Total Files

    110

    Last publish

    Collaborators

    • raheeljameel