ngx-ui-loader

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

Features

• Support custom template (>= ngx-ui-loader@9.1.0).
• Support multiple loaders (>= ngx-ui-loader@7.1.0).
• Show foreground loader with progress bar
• The page content can be blurred/frosted while showing foreground loader. See NgxUiLoaderBlurred directive for more details
• Automatically show loader for router events. See NgxUiLoaderRouterModule for more details
• Automatically show loader for http requests. See NgxUiLoaderHttpModule for more details

Demo

Live demo here.

Minimal setup here on Stackblitz.

Custom template here on Stackblitz.

Simple setup for multiple loaders here on Stackblitz.

Multiple loaders with feature modules here

Live demo source code here on Stackblitz.

Getting Started

Installation

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

$ npm install --save ngx-ui-loader

# Or Yarn

$ yarn add ngx-ui-loader

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 {}

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.

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 that you can call it anywhere in your 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.

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.

API - NgxUiLoaderService

• NgxUiLoaderService.start([taskId]='default', [time]) 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', [time]) 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', [time]) 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', [time]) 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.

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:

NgxUiLoaderBlurred directive

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>

Attributes:

Custom template

Usage

You can add your own template for foreground spinner (fgsTemplate) and background spinner bgsTemplate as below:

<ngx-ui-loader
  [fgsTemplate]="foregroundSpinner"
  [bgsTemplate]="backgroundSpinner"
></ngx-ui-loader>

<ng-template #foregroundSpinner>
  <!-- Your awesome foreground spinner defined here -->
</ng-template>

<ng-template #backgroundSpinner>
  <!-- Your awesome background spinner defined here -->
</ng-template>

See custom template example here on Stackblitz.

See here for more spinners from Daniel Cardoso.

Custom configuration for NgxUiLoaderModule

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 {}

Parameters of forRoot() method

Automatically show loader for router events

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 {}

Parameters of forRoot() method

Automatically show loader for Http requests

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 not to 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"],
});

Parameters of forRoot() method

Changelog

See Changelog here

Credits

• Tobias Ahlin - CSS spinkit
• Daniel Cardoso - Load awesome
• Matt Carter - AngularJS angular-ui-loader

License

MIT © t-ho