ngx spinner

A library for loading spinner for Angular 4 - 17.

Napster2210
828
141
CSS

A library with more than 50 different loading spinners for Angular 4 - 17. (https://napster2210.github.io/ngx-spinner/)

NgxSpinner

Support
Support
Support
Support
Support
Support
Support
Support
Support
Support
Support
Support
Support
Support
License
Gitter

What’s New

  • Angular 17 support 🥳🥳🥳🥳

Use appropriate version based on your Angular version.

Angular 17 Angular 16 Angular 15
>=v17.0.0 >=v16.0.2 >=v15.0.1
Angular 14 Angular 13 Angular 12 Angular 11 Angular 10
>=v14.0.0 >=v13.1.1 >=v12.0.0 >=v11.0.2 >=v10.0.1
Angular 9 Angular 8 Angular 6/7 Angular 5 Angular 4
>=v9.0.1 v8.1.0 v7.2.0 >=v1.2.0 >=v2.0.0

Table of contents

Browser Support

Chrome
Chrome		 Firefox
Firefox		 IE / Edge
IE / Edge		 iOS Safari
Safari		 Opera
Opera
Latest ✔ Latest ✔ IE11, Edge ✔ Latest ✔ Latest ✔

Features

  • Angular 17 Support
  • Custom spinner image support(gif), you can pass img tag
  • Multiple Spinners
  • Configurable option through service
  • Fullscreen Mode(Enable/Disable)
  • show()/hide() methods return promise
  • Dynamic z-index
  • Smooth animation while hide/show the spinner
  • New updated DEMO website
  • Option to disable fade animation
  • Show/Hide spinner from template using @Input() variable
  • Smaller bundle size

Demo

Working Demo

StackBlitz Demo

Installation

ngx-spinner is available via npm and yarn

Using npm:

$ npm install ngx-spinner --save

Using yarn:

$ yarn add ngx-spinner

Using angular-cli:

$ ng add ngx-spinner

Usage

Add css animation files to angular.json config

{
  "styles": [
    "node_modules/ngx-spinner/animations/ball-scale-multiple.css" // ===> Add css file based on your animation name(here it's "ball-scale-multiple")
    // You're able to add multiple files if you need
  ]
}

Import NgxSpinnerModule in in the root module(AppModule):

import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
import { BrowserAnimationsModule } from "@angular/platform-browser/animations";
// Import library module
import { NgxSpinnerModule } from "ngx-spinner";

@NgModule({
  imports: [
    // ...
    BrowserAnimationsModule,
    NgxSpinnerModule,
  ],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

NOTE

  • There is possibility to use global configuration for NgxSpinnerModule.
  • Just call forRoot method for NgxSpinnerModule and pass configuration object.
  • The input properties of NgxSpinnerComponent has higher priority than global options
// Available options
interface NgxSpinnerConfig {
  type?: string;
}
// Use in app
@NgModule({
  imports: [
    NgxSpinnerModule.forRoot({ type: 'ball-scale-multiple' })
  ]
})

Add NgxSpinnerService service wherever you want to use the ngx-spinner.

import { NgxSpinnerService } from "ngx-spinner";

class AppComponent implements OnInit {
  constructor(private spinner: NgxSpinnerService) {}

  ngOnInit() {
    /** spinner starts on init */
    this.spinner.show();

    setTimeout(() => {
      /** spinner ends after 5 seconds */
      this.spinner.hide();
    }, 5000);
  }
}

Now use in your template

<ngx-spinner type="ball-scale-multiple"></ngx-spinner>

See Demo

Methods

  • NgxSpinnerService.show() Shows the spinner
  • NgxSpinnerService.hide() Hides the spinner

Available Options

  • [bdColor]: RGBA color format.
    To set background-color for backdrop, default rgba(51,51,51,0.8) where alpha value(0.8) is opacity of backdrop
  • [size]: Anyone from small, default, medium, large.
    To set size of spinner, default large
  • [color]: Any css color format.
    To set color of spinner, default #fff
  • [type]: Choose any animation spinner from Load Awesome.
    To set type of spinner
  • [fullScreen]: true or false
    To enable/disable fullscreen mode(overlay), default true
  • [name]: For multiple spinners
    To set name for spinner, default primary
  • [zIndex]: For dynamic z-index
    To set z-index for the spinner, default 99999
  • [template]: For custom spinner image
    To set custom template for the custom spinner, default null
  • [showSpinner]: true or false
    To show/hide spinner from template using variable
  • [disableAnimation]: true or false
    To enable/disable fade animation of spinner, default false

Using Spinner Type

<ngx-spinner
  bdColor="rgba(51,51,51,0.8)"
  size="medium"
  color="#fff"
  type="ball-scale-multiple"
>
  <p style="font-size: 20px; color: white">Loading...</p>
</ngx-spinner>

Using Custom Spinner

<ngx-spinner
  bdColor="rgba(0, 0, 0, 1)"
  template="<img src='https://media.giphy.com/media/o8igknyuKs6aY/giphy.gif' />"
>
</ngx-spinner>

NOTE

  • You can pass HTML code as loading text now, instead of input parameter(loadingText). Check above code for reference.
  • If you want multiple ngx-spinner instance, just add name attribute with ngx-spinner component. But in this case, you’ve to pass that particular name of a spinner in show/hide method. Check Demo
  • You can also change the options/configuration of spinner through service now.
  • For smaller bundle size, add specific css file under “styles” array in angular.json file
this.spinner.show("mySpinner", {
  type: "line-scale-party",
  size: "large",
  bdColor: "rgba(0, 0, 0, 1)",
  color: "white",
  template:
    "<img src='https://media.giphy.com/media/o8igknyuKs6aY/giphy.gif' />",
});

How to use type?

  • Go to the Load Awesome.
  • Select any animation, copy name of animation, replace all spaces with hyphen(-) and all letters should be lowercase.
    • Let’s say if I select “Ball 8bits” animation then type will be ball-8bits.
    • For more information you can check it out Demo
    • For smaller bundle size you need to add css for ball-8bits animation(e.g. ball-8bits.css)

Useful Tips

  • Make sure you’ve added CUSTOM_ELEMENTS_SCHEMA as your schema in your main module.
  • If you use multiple show() methods in a single component or single function one after another then wrap the show() method within setTimeout() method to avoid any rendering issue.
  • When you want to use spinner inside any container(fullScreen: false), in that case your parent element of spinner must have position: relative; style property.
  • You can’t set custom template through service options, it’s a limitation by Angular itself.

Versioning

ngx-spinner will be maintained under the Semantic Versioning guidelines.
Releases will be numbered with the following format:

<major>.<minor>.<patch>

For more information on SemVer, please visit http://semver.org.

Creator

Yuvraj Chauhan

Future Plan

  • Interceptor Implementation

Ask Me

  • Now you can directly send me a message on Gitter for any query/suggestion/updates

Credits

Inspired by Load Awesome by Daniel Cardoso.

Thanks Alex Vieira Alencar for helping me with Multiple Spinner Support.

Thanks ennjin for reducing the bundle size.

License

ngx-spinner is MIT licensed.