Skip to content

Latest commit

 

History

History
498 lines (370 loc) · 28 KB

README.md

File metadata and controls

498 lines (370 loc) · 28 KB
Raw

npm version demo Build Status codecov npm npm bundle size (minified + gzip) license

NOTE: This is the documentations for v7.x.x

Please see Wiki page for other versions

ngx-ui-loader

An all-in-one and fully customizable loader/spinner for Angular 5, 6 and 7+ applications. It supports foreground, background spinner/loader, indicative progress bar and multiple loaders.

ngx-ui-loader-demo

Available spinners:

ngx-ui-loader-spinners

Features

  • Support multiple loaders (>= ngx-ui-loader@7.1.0). See Multiple loaders for more details and demo here
  • Show foreground loader with progress bar
  • The page content can be blurred/frosted while showing foreground loader. See NgxUiLoaderBlurred directive for more details
  • Show loader with different id for different tasks
  • Be able to add logo and loading text
  • Be able to change position of spinners, logo and loading text
  • Be able to change color and size of logo, spinners and progress bar
  • Be able to change the direction of progress bar
  • Automatically show loader for router events. See NgxUiLoaderRouterModule for more details
  • Automatically show loader for http requests. See NgxUiLoaderHttpModule for more details

Table Of Contents

  1. Demo
  2. Getting Started
    2.1 Install
    2.2 Import NgxUiLoaderModule
    2.3 Include ngx-ui-loader component
    2.4 Use NgxUiLoaderService service
  3. API - NgxUiLoaderService
  4. Attributes of NgxUiLoaderComponent
  5. NgxUiLoaderBlurred directive
    5.1 Usage
    5.2 Attributes
  6. Custom configuration for NgxUiLoaderModule
    6.1 Usage
    6.2 Parameters of forRoot() method
  7. Automatically show loader for router events
    7.1 Usage
    7.2 Parameters of forRoot() method
  8. Automatically show loader for http requests
    8.1 Usage
    8.2 Parameters of forRoot() method

1. Demo

Live demo here.

Multiple loaders demo here.

Live demo source code here on Stackblitz.

2. Getting started

2.1 Install

Install ngx-ui-loader via NPM, using the command below.

NPM

$ npm install --save ngx-ui-loader@7.2.2

Or Yarn

$ yarn add ngx-ui-loader@7.2.2
* For Angular 4 and 5, please use ngx-ui-loader version 1.2.x
$ npm install --save ngx-ui-loader@1.2.5

The documentation for v1.2.x is available here

2.2 Import NgxUiLoaderModule

Import the NgxUiLoaderModule in your root application module AppModule:

import { BrowserModule } from  '@angular/platform-browser';
import { NgModule } from  '@angular/core';

import { AppComponent } from './app.component';

import { NgxUiLoaderModule } from  'ngx-ui-loader';

@NgModule({
  declarations: [
    AppComponent,
  ],
  imports: [
    BrowserModule,
    // Import NgxUiLoaderModule
    NgxUiLoaderModule,
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

2.3 Include ngx-ui-loader component

After importing the NgxUiLoaderModule, use ngx-ui-loader component in your root app template:

<ngx-ui-loader></ngx-ui-loader>

See Attributes of NgxUiLoaderComponent for more details about attributes.

See minimal setup here on Stackblitz.

2.4 Multiple loaders

You can skip this step if you do not want to use multiple loaders

After importing the NgxUiLoaderModule, use ngx-ui-loader component in your template:

<div style="position: relative"> <!-- the position of the parent container must be set to relative -->
  <!-- It is really important to set loaderId for non-master loader -->
  <ngx-ui-loader [loaderId]="'loader-01'"></ngx-ui-loader>
</div>

<div style="position: relative"> <!-- the position of the parent container must be set to relative -->
  <!-- It is really important to set loaderId for non-master loader -->
  <ngx-ui-loader [loaderId]="'loader-02'"></ngx-ui-loader>
</div>

<ngx-ui-loader></ngx-ui-loader> <!-- this is master loader and its loaderId is "master" by default -->
<!-- Note 1: If you really want to change loaderId of master loader, please use NgxUiLoaderModule.forRoot() method. -->
<!-- Note 2: Your application can only have ONE master loader.
             The master loader should be placed in your app root template, so you can call it anywhere in you app. -->

See simple setup for multiple loaders here on Stackblitz.

Note:

  • The application can have only one master loader and many non-master loaders.
  • The master loader will block the entire viewport.

2.5 Use NgxUiLoaderService service

Add NgxUiLoaderService service wherever you want to use the ngx-ui-loader:

import { Component, OnInit } from '@angular/core';
import { NgxUiLoaderService } from 'ngx-ui-loader'; // Import NgxUiLoaderService

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent implements OnInit {

  constructor(private ngxService: NgxUiLoaderService) { }

  ngOnInit() {
    this.ngxService.start(); // start foreground spinner of the master loader with 'default' taskId
    // Stop the foreground loading after 5s
    setTimeout(() => {
      this.ngxService.stop(); // stop foreground spinner of the master loader with 'default' taskId
    }, 5000);

    // OR
    this.ngxService.startBackground('do-background-things');
    // Do something here...
    this.ngxService.stopBackground('do-background-things');

    this.ngxService.startLoader('loader-01'); // start foreground spinner of the loader "loader-01" with 'default' taskId
    // Stop the foreground loading after 5s
    setTimeout(() => {
      this.ngxService.stopLoader('loader-01'); // stop foreground spinner of the loader "loader-01" with 'default' taskId
    }, 5000);
  }
}

See API - NgxUiLoaderService for more details.

3. API - NgxUiLoaderService

  • NgxUiLoaderService.start([taskId]='default') Starts a foreground spinner with progress bar of the master loader. Users cannot interact with the page when the loader is showed.

  • NgxUiLoaderService.stop([taskId]='default') Stops a foreground spinner with progress bar of the master loader.

  • NgxUiLoaderService.startBackground([taskId]='default') Starts a background spinner of the master loader. Users can interact with the page when the loader is showed.

  • NgxUiLoaderService.stopBackground([taskId]='default') Stops a background spinner of the master loader.

  • NgxUiLoaderService.startLoader(loaderId, [taskId]='default') Starts a foreground spinner with progress bar of a specified loader. Users cannot interact with the page when the loader is showed.

  • NgxUiLoaderService.stopLoader(loaderId, [taskId]='default') Stops a foreground spinner with progress bar of a specified loader.

  • NgxUiLoaderService.startBackgroundLoader(loaderId, [taskId]='default') Starts a background spinner of a specified loader. Users can interact with the page when the loader is showed.

  • NgxUiLoaderService.stopBackgroundLoader(loaderId, [taskId]='default') Stops a background spinner of a specified loader.

  • NgxUiLoaderService.getDefaultConfig() Returns the default configuration object of ngx-ui-loader.

  • NgxUiLoaderService.getLoader([loaderId]) Return a specified loader. If no loaderId given, it will return master loader (if exist).

  • NgxUiLoaderService.getLoaders() Return the all of loaders.

  • NgxUiLoaderService.getStatus() Deprecated - will be remove in version 8.x.x.

  • NgxUiLoaderService.stopAll() Stops all foreground and background loadings/spinners of master loader.

4. Attributes of NgxUiLoaderComponent

You can configure ngx-ui-loader in the template as below:

Import the constant SPINNER from ngx-ui-loader in your controller. Then in your template:

<ngx-ui-loader fgsSize="75" [fgsType]="SPINNER.wanderingCubes"></ngx-ui-loader>

All attributes are listed below:

Attribute Type Required Default Description
bgsColor string optional #00ACC1 Background spinner color
bgsOpacity number optional 0.5 Background spinner opacity
bgsPosition string optional bottom-right Background spinner postion. All available positions can be accessed via POSITION
bgsSize number optional 60 Background spinner size.
bgsType string optional ball-spin-clockwise Background spinner type. All available types can be accessed via SPINNER
fgsColor string optional #00ACC1 Foreground spinner color
fgsPosition string optional center-center Foreground spinner position. All available positions can be accessed via POSITION
fgsSize number optional 60 Foreground spinner size.
fgsType string optional ball-spin-clockwise Foreground spinner type. All available types can be accessed via SPINNER
logoPosition string optional center-center Logo position. All available positions can be accessed via POSITION
logoSize number optional 120 Logo size (px)
logoUrl string optional (empty string) Logo url
pbColor string optional #00ACC1 Progress bar color
pbDirection string optional ltr Progress bar direction. All direction types can be accessed via PB_DIRECTION
pbThickness number optional 3 Progress bar thickness
hasProgressBar boolean optional true Show the progress bar while loading foreground
text string optional (empty string) Loading text
textColor string optional #FFFFFF Loading text color
textPosition string optional center-center Loading text position. All available positions can be accessed via POSITION
gap number optional 24 The gap between logo, foreground spinner and text when their positions are center-center
loaderId string optional master The loader ID
overlayBorderRadius string optional 0 Overlay border radius
overlayColor string optional rgba(40,40,40,.8) Overlay background color

5. NgxUiLoaderBlurred directive

5.1 Usage

If you want your page content is blurred/frosted while showing foreground loader, use ngxUiLoaderBlurred directive in your root template as follow:

<div ngxUiLoaderBlurred blur="10">
  <!-- This page content will be blurred/frosted when foreground loader is showed -->
</div>
<ngx-ui-loader></ngx-ui-loader>

5.2 Attributes:

Attribute Type Required Default Description
blur number optional 5 Blur the page content while showing foreground loader.
loaderId string optional master The loader id that this blurred directive attached to. By default, loaderId = DefaultConfig.masterLoaderId

6. Custom configuration for NgxUiLoaderModule

6.1 Usage

You can override the default configuration via forRoot() method.

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';

import { AppComponent } from './app.component';

import { NgxUiLoaderModule, NgxUiLoaderConfig, SPINNER, POSITION, PB_DIRECTION } from 'ngx-ui-loader';

const ngxUiLoaderConfig: NgxUiLoaderConfig = {
  bgsColor: 'red',
  bgsPosition: POSITION.bottomCenter,
  bgsSize: 40,
  bgsType: SPINNER.rectangleBounce, // background spinner type
  fgsType: SPINNER.chasingDots, // foreground spinner type
  pbDirection: PB_DIRECTION.leftToRight, // progress bar direction
  pbThickness: 5, // progress bar thickness
};

@NgModule({
  declarations: [
    AppComponent,
  ],
  imports: [
    BrowserModule,
    // Import NgxUiLoaderModule with custom configuration globally
    NgxUiLoaderModule.forRoot(ngxUiLoaderConfig)
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

6.2 Parameters of forRoot() method

Parameter Type Required Default Description
bgsColor string optional #00ACC1 Background spinner color
bgsOpacity number optional 0.5 Background spinner opacity
bgsPosition string optional bottom-right Background spinner postion. All available positions can be accessed via POSITION
bgsSize number optional 60 Background spinner size.
bgsType string optional ball-spin-clockwise Background spinner type. All available types can be accessed via SPINNER
fgsColor string optional #00ACC1 Foreground spinner color
fgsPosition string optional center-center Foreground spinner position. All available positions can be accessed via POSITION
fgsSize number optional 60 Foreground spinner size.
fgsType string optional ball-spin-clockwise Foreground spinner type. All available types can be accessed via SPINNER
logoPosition string optional center-center Logo position. All available positions can be accessed via POSITION
logoSize number optional 120 Logo size (px)
logoUrl string optional (empty string) Logo url
pbColor string optional #00ACC1 Progress bar color
pbDirection string optional ltr Progress bar direction. All direction types can be accessed via PB_DIRECTION
pbThickness number optional 3 Progress bar thickness
hasProgressBar boolean optional true Show the progress bar while loading foreground
text string optional (empty string) Loading text
textColor string optional #FFFFFF Loading text color
textPosition string optional center-center Loading text position. All available positions can be accessed via POSITION
blur number optional 5 Blur the page content while showing foreground loader. Only applied when using ngxUiLoaderBlurred directive.
gap number optional 24 The gap between logo, foreground spinner and text when their positions are center-center
masterLoaderId string optional master The default value for master's loaderId
overlayBorderRadius string optional 0 Overlay border radius
overlayColor string optional rgba(40,40,40,.8) Overlay background color
threshold number optional 500 The time a loader must be showed at least before it can be stopped. It must be >= 1 millisecond.

7. Automatically show loader for router events

7.1 Usage

If you want the loader to start automatically for navigating between your app routes, in your root AppModule, do as follow:

import { BrowserModule } from  '@angular/platform-browser';
import { NgModule } from  '@angular/core';

import { AppComponent } from './app.component';

import { NgxUiLoaderModule, NgxUiLoaderRouterModule } from  'ngx-ui-loader';

@NgModule({
  declarations: [
    AppComponent,
  ],
  imports: [
    BrowserModule,
    NgxUiLoaderModule, // import NgxUiLoaderModule
    NgxUiLoaderRouterModule, // import NgxUiLoaderRouterModule. By default, it will show foreground loader.
    // If you need to show background spinner, do as follow:
    // NgxUiLoaderRouterModule.forRoot({ showForeground: false })
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

7.2 Parameters of forRoot() method

Parameter Type Required Default Description
loaderId string optional master Specify the loader id which will showed when navigating between app routes. By default, loaderId = DefaultConfig.masterLoaderId
showForeground boolean optional true If true, foreground loader is showed. Otherwise, background loader is showed.

8. Automatically show loader for Http requests

8.1 Usage

If you want the loader to start automatically for http requests, in your root AppModule, do as follow:

import { BrowserModule } from  '@angular/platform-browser';
import { NgModule } from  '@angular/core';
import { HttpClientModule } from '@angular/common/http';

import { AppComponent } from './app.component';

import { NgxUiLoaderModule, NgxUiLoaderHttpModule } from  'ngx-ui-loader';

@NgModule({
  declarations: [
    AppComponent,
  ],
  imports: [
    BrowserModule,
    HttpClientModule, // import HttpClientModule
    NgxUiLoaderModule, // import NgxUiLoaderModule
    NgxUiLoaderHttpModule, // import NgxUiLoaderHttpModule. By default, it will show background loader.
    // If you need to show foreground spinner, do as follow:
    // NgxUiLoaderHttpModule.forRoot({ showForeground: true })
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

If you wish to not show loader for some specific API urls, you can pass an array of these urls (case-insensitive) to forRoot() method as below:

NgxUiLoaderHttpModule.forRoot({ exclude: ['/api/not/show/loader', '/api/logout', 'https://external-domain.com/api/not/to/show'] });

or if you don't want to show loader for urls which start with /api/auth or https://external-domain.com/api/auth, do as follow:

NgxUiLoaderHttpModule.forRoot({ exclude: ['/api/auth'] });
// Or
NgxUiLoaderHttpModule.forRoot({ exclude: ['https://external-domain.com/api/auth'] });

8.2 Parameters of forRoot() method

Parameter Type Required Default Description
exclude string[] optional null The loader is not showed when making request to the API urls that start with these strings. Upper/lower case differences will be ignored.
excludeRegexp string[] optional null An array of regexp strings. The loader is not showed when making request to the API urls that match these regexps. Upper/lower case differences will be ignored.
loaderId string optional master Specify the loader id which will showed when making http requests. By default, loaderId = DefaultConfig.masterLoaderId
showForeground boolean optional false If true, foreground loader is showed. Otherwise, background loader is showed.

If you like ngx-ui-loader, please give it a ⭐