Angular HTTP Loader and Spinner

Common errors

• ERROR in Error: Metadata version mismatch for module [...]/angular/node_modules/ng-http-loader/ng-http-loader.module.d.ts, found version x, expected y [...]

  cause The installed version of ng-http-loader is incompatible with your current Angular major version.
  fix Install the ng-http-loader version that precisely matches your Angular major version, as detailed in the package's compatibility table (e.g., `npm install ng-http-loader@19` for Angular 21).

• NG0901: Some of the providers were not statically analyzable. We cannot determine their dependencies or their type.

  cause This error often occurs when trying to use functional interceptors (like `pendingRequestsInterceptor$`) with older Angular module-based provider configurations or incorrect injection tokens.
  fix Ensure you are using `provideHttpClient(withInterceptors([pendingRequestsInterceptor$]))` in your `ApplicationConfig` for standalone apps, or in your `NgModule`'s `providers` array for module-based apps, and that `@angular/common/http` is correctly imported.

Warnings

• breaking Starting from v17.1.0, ng-http-loader transitioned from `@Input` decorators to Angular signals for component inputs. This aligns with modern Angular practices but requires users to update their input binding syntax if upgrading from older versions.
  Fix: Migrate component input bindings from property binding (`[property]="value"`) to signal-based syntax or ensure you are using a compatible ng-http-loader version for your application's input style.
• breaking Version 17.2.0 deprecated and removed `model()` in favor of `input()`. Applications using `model()` for two-way binding with ng-http-loader components will need to refactor.
  Fix: Replace usages of `model()` with `input()` as per Angular's signal-based input changes. Review ng-http-loader's documentation for updated input properties.
• breaking Version 17.3.0 introduced 'zoneless' support, which may impact applications relying on Angular's NgZone for change detection or specific side effects within the loader's lifecycle. While generally an improvement, it might require adjustments in specific edge cases.
  Fix: Review application code that might explicitly interact with `NgZone` or rely on specific change detection cycles related to HTTP requests. Test thoroughly after upgrading to ensure consistent behavior.
• gotcha The `ng-http-loader` library *requires* Angular's `HttpClient` for its functionality. If you are using an older HTTP client (e.g., the deprecated `HttpModule` from `@angular/http`) or not using HTTP requests at all, the spinner will not activate.
  Fix: Ensure your application uses `HttpClient` from `@angular/common/http` for all HTTP requests. For standalone applications, provide `provideHttpClient` in your application config. For NgModules, import `HttpClientModule`.
• breaking Major versions of `ng-http-loader` are tightly coupled with Angular's major versions. Using a version of `ng-http-loader` that is incompatible with your Angular version will result in runtime errors related to metadata mismatch.
  Fix: Always consult the compatibility table in the README or package documentation to ensure you install the `ng-http-loader` version that explicitly supports your Angular major version (e.g., ng-http-loader v19 for Angular v21).

Install

• npm install ng-http-loader npm
• yarn add ng-http-loader yarn
• pnpm add ng-http-loader pnpm

Imports

• NgHttpLoaderComponent
  wrong:

  import NgHttpLoaderComponent from 'ng-http-loader';

  correct:

  import { NgHttpLoaderComponent } from 'ng-http-loader';

  This is a named export for the standalone component, typically imported directly into an Angular component's `imports` array.
• pendingRequestsInterceptor$
  wrong:

  import pendingRequestsInterceptor from 'ng-http-loader';

  correct:

  import { pendingRequestsInterceptor$ } from 'ng-http-loader';

  This is a functional HTTP interceptor, intended for use with Angular's `provideHttpClient(withInterceptors([...]))` function (since Angular 15.2+).
• NgHttpLoaderModule
  wrong:

  const NgHttpLoaderModule = require('ng-http-loader');

  correct:

  import { NgHttpLoaderModule } from 'ng-http-loader';

  Used for traditional Angular modules (NgModules) in non-standalone applications, imported into the module's `imports` array. ng-http-loader is ESM-only.

Quickstart

This quickstart demonstrates how to integrate `ng-http-loader` into a modern Angular standalone application, including importing the loader component and configuring the functional HTTP interceptor.

import { ApplicationConfig, importProvidersFrom } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideHttpClient, withInterceptors } from '@angular/common/http';
import { NgHttpLoaderComponent, pendingRequestsInterceptor$ } from 'ng-http-loader';
import { Component } from '@angular/core';

// app.component.ts
@Component({
    selector: 'app-root',
    standalone: true,
    template: `
        <h1>My Angular App</h1>
        <ng-http-loader></ng-http-loader>
        <router-outlet></router-outlet>
    `,
    styles: [`h1 { color: #333; }`],
    imports: [NgHttpLoaderComponent] // <====== import the component
})
export class AppComponent {
    title = 'my-angular-app';
}

// app.config.ts
import { routes } from './app.routes'; // Assuming you have app.routes defined
export const appConfig: ApplicationConfig = {
    providers: [
        provideRouter(routes),
        provideHttpClient(withInterceptors([pendingRequestsInterceptor$])),
    ],
};

// Example of app.routes.ts (for context)
// import { Routes } from '@angular/router';
// export const routes: Routes = [];