ngx-ui-loader

ngx-ui-loader

An all-in-one and fully customizable loader/spinner for Angular 5+ (5+ and 6+ are tested) applications. It supports foreground, background spinner/loader and indicative progress bar.

Available spinners:

Features

• Show foreground loader with progress bar
• 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. NOTE: When they are all set to center-center, the gap between them are adjusted via gap properties. Other position types are is overlap. E.g. If the position of foreground spinner and logo are set to bottom-center, they are overlap each other.
• Be able to change color and size of logo, spinners and progress bar
• Be able to change the direction of progress bar

Table Of Contents

• Demo
• Installation
• Getting Started
• Usage
• API - NgxUiLoaderService
• Custom Configuration
• Input options
• Automatically show loader for router events
• Automatically show loader for http requests
• Changelog
• Credits
• License

Demo

Live demo here.

Play with ngx-ui-loader here on stackblitz.

Installation

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

NPM

npm install --save ngx-ui-loader

Getting started

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

Usage

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

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

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 loading with 'default' id

    // Stop the foreground loading after 5s
    setTimeout(() => {
      this.ngxService.stop(); // stop foreground loading with 'default' id
    }, 5000);

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

API - NgxUiLoaderService

• NgxUiLoaderService.start([id]='default') Starts a foreground loader with progress bar. Users cannot interact with the page when the loader is showed.
• NgxUiLoaderService.stop([id]='default') Stops a foreground loader with progress bar.
• NgxUiLoaderService.startBackground([id]='default') Starts a background loader. Users can interact with the page when the loader is showed.
• NgxUiLoaderService.stopBackground([id]='default') Stops a background loader.
• NgxUiLoaderService.getDefaultConfig() Returns the default configuration object of ngx-ui-loader.
• NgxUiLoaderService.getStatus() Returns an object including waitingForeground and waitingBackground properties.
• NgxUiLoaderService.stopAll() Stops all foreground and background loaders.

Custom Configuration

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

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

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

Or 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_TYPES, NGX_POSITIONS, PB_DIRECTIONS } from 'ngx-ui-loader';

const ngxUiLoaderConfig: NgxUiLoaderConfig = {
  bgsColor: 'red',
  bgsPosition: NGX_POSITIONS.bottomCenter,
  bgsSize: 40,
  bgsType: SPINNER_TYPES.rectangleBounce,
  pbDirection: PB_DIRECTIONS.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 { }

Input Options

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 NGX_POSITIONS
bgsSize	number	optional	60	Background spinner size.
bgsType	string	optional	rectangle-bounce	Background spinner type. All available types can be accessed via SPINNER_TYPES
fgsColor	string	optional	#00ACC1	Foreground spinner color
fgsPosition	string	optional	center-center	Foreground spinner position. All available positions can be accessed via NGX_POSITIONS
fgsSize	number	optional	60	Foreground spinner size.
fgsType	string	optional	rectangle-bounce	Foreground spinner type. All available types can be accessed via SPINNER_TYPES
logoPosition	string	optional	center-center	Logo position. All available positions can be accessed via NGX_POSITIONS
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 directions type can be accessed via PB_DIRECTIONS
pbThickness	number	optional	5	Progress bar thickness
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 NGX_POSITIONS
gap	number	optional	24	The gap between logo, foreground spinner and text when their positions are center-center
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. NOTE: threshold is only configured via forRoot() method.

Automatically show loader for router events

If you want the loader to start automatically for navigating between your app routes:

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

Automatically show loader for Http requests

If you want the loader to start automatically for http requests:

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,
    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'] });

or if you don't want to show loader for urls which start with /api/auth, do as follow:

NgxUiLoaderHttpModule.forRoot({ exclude: ['/api/auth'] });

NOTE: And in you root app template, do not forget to include ngx-ui-loader component:

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

Changelog

v.1.1.8

• Http interceptor - Can configure to not show loader for some API urls.
• Npm packages - version bump.

v.1.1.5

• Be able to show loader automatically for http requests - Http interceptor

v.1.1.2

• Add more spinner types (total 22 spinners)
• Bugs fixed: Background spinner (if active) should be showed after the foreground spinner is closed out.

v.1.1.1

• Bugs fixed

v.1.1.0

Features

• Show loader automatically when navigating between app routes
• Add more spinner types
• Be able to set a threshold

Bugs Fixed

• Set z-index of background spinner to 99999

v.1.0.2

• Update example app and README.md

v.1.0.1

Bugs fixed

• Position of background spinner is not fixed when scrolling
• Unsafe Base64 logo url
• Logo, foreground spinner and loading text are centered correctly and can set the gap between them via gap input

v.1.0.0

Features

• Show foreground loader with progress bar
• Show background loader with different id for different tasks
• There are 12 spinner types available
• 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 spinners and progress bar
• Be able to change the direction of progress bar

Credits

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

License

MIT © t-ho

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.