Skip to main content
current (v21)

Installation and Configuration

Installation​

Install the package via npm:

npm install @ng-catbee/loader

Import Animation Styles​

Important: You must import the CSS file for each animation style you want to use. Each animation has its own CSS file.

Add the animation styles you need to your global styles.css or styles.scss file:

/* Import the animation style you need */
@import 'node_modules/@ng-catbee/loader/css/ball-spin-clockwise.css';

/* Or import multiple animations */
@import 'node_modules/@ng-catbee/loader/css/ball-grid-pulse.css';
@import 'node_modules/@ng-catbee/loader/css/line-scale.css';
@import 'node_modules/@ng-catbee/loader/css/pacman.css';

Option 2: Add to angular.json styles array​

Alternatively, you can add the CSS files to your angular.json styles array:

{
  "styles": [
    "src/styles.css",
    "node_modules/@ng-catbee/loader/css/ball-spin-clockwise.css",
    "node_modules/@ng-catbee/loader/css/line-scale.css"
  ]
}
tip

You only need to import the CSS files for the animations you actually use in your application. This keeps your bundle size small.

Global Configuration (Optional)​

You can configure default settings for all loaders in your application.

Standalone Applications​

In your app.config.ts:

import { ApplicationConfig } from '@angular/core';
import { provideCatbeeLoader } from '@ng-catbee/loader';

export const appConfig: ApplicationConfig = {
  providers: [
    provideCatbeeLoader({
      animation: 'ball-spin-clockwise',
      size: 'medium',
      backgroundColor: 'rgba(0, 0, 0, 0.8)',
      loaderColor: '#ffffff',
      zIndex: 999999,
      fullscreen: true
    })
  ]
};

Module-Based Applications​

In your app.module.ts:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { CatbeeLoaderModule } from '@ng-catbee/loader';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    CatbeeLoaderModule.forRoot({
      animation: 'ball-spin-clockwise',
      size: 'medium',
      backgroundColor: 'rgba(0, 0, 0, 0.8)',
      loaderColor: '#ffffff',
      zIndex: 999999,
      fullscreen: true
    })
  ],
  bootstrap: [AppComponent]
})
export class AppModule { }

Configuration Options​

OptionTypeDefaultDescription
animationCatbeeLoaderAnimation'ball-spin-clockwise'Default animation style for all loaders
size'small' | 'medium' | 'large''medium'Default size for all loaders
backgroundColorstring'rgba(0,0,0,0.7)'Default overlay background color
loaderColorstring'#ffffff'Default loader/spinner color
zIndexnumber999999Default CSS z-index value
fullscreenbooleantrueDefault fullscreen overlay mode
messagestring | nullnullDefault loading message text
customTemplatestring | nullnullDefault custom HTML template
info

Global configuration sets defaults for all loaders. You can override these settings per-loader by passing options to the component inputs or the show() method.

Basic Setup​

After installation and configuration, you're ready to use the loader in your components:

import { Component, inject } from '@angular/core';
import { CatbeeLoader, CatbeeLoaderService } from '@ng-catbee/loader';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CatbeeLoader],
  template: `
    <ng-catbee-loader />

    <button (click)="showLoader()">Show Loader</button>
    <button (click)="hideLoader()">Hide Loader</button>
  `,
})
export class AppComponent {
  private loaderService = inject(CatbeeLoaderService);

  async showLoader() {
    await this.loaderService.show('default');
  }

  async hideLoader() {
    await this.loaderService.hide('default');
  }
}

Angular Compatibility​

Angular VersionSupported
v17 and above✅ Fully supported

This library is built and tested with Angular 20.x, and supports all modern standalone-based Angular projects (v17+).

Next Steps​