ngx-ui-loader

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.

Available 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 background loader with different id for different tasks
• Be able to add logo, 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

The full documentation is available at the wiki page

Table Of Contents

1. Demo
2. Getting Started
   2.1 Install
   2.2 Import NgxUiLoaderModule
   2.3 Include ngx-ui-loader component
   2.4 Multiple loaders
   2.5 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
9. Changelog
10. Credits
11. License

Demo

Live demo here.

Multiple loaders demo here.

Minimal setup here on Stackblitz.

Simple setup for multiple loaders here on Stackblitz.

Live demo source code here on Stackblitz.

If you like it, please star on Github.

Getting started

Install

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

NPM

$ npm install --save ngx-ui-loader

Or Yarn

$ yarn add ngx-ui-loader

* For Angular 4 and 5, please use ngx-ui-loader version 1.2.x

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

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.

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 loader.
• 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.

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