ngx-spinner: an Angular loading spinner library with fifty animations and an HTTP interceptor

What the library is, and the scale of the version matrix

ngx-spinner is an Angular library with more than fifty different loading spinners, described as supporting Angular 4 to 22. The repository description is fuller: highly customizable loading spinners with fifty or more animations, multiple named spinners, an optional HTTP interceptor for automatic show and hide, MatDialog-safe fullscreen overlays via the Popover API, and one-command ng add setup, with support for both standalone and NgModule applications.

The version matrix is the thing to understand first, because the project does not follow the usual Angular library convention of shipping one major per Angular major with the version number aligned. Instead it publishes a release line for each Angular version, and the README's tables give the mapping. Angular 22 needs at least v22.0.0, Angular 21 needs at least v21.0.0, Angular 19 needs at least v19.0.0, and Angular 18 needs at least v18.0.0, going back through Angular 16 which needs v16.0.2, Angular 12 which needs v12.0.0, Angular 9 which needs v9.0.1, Angular 8 which is pinned at v8.1.0 and Angular 6 or 7 at v7.2.0.

There is one oddity in that table worth flagging rather than smoothing over. The oldest rows read Angular 5 needing at least v1.2.0 and Angular 4 needing at least v2.0.0, which means the version number decreases as the Angular version increases for the two oldest entries. That is either a deliberate naming choice or a leftover, and either way it means the oldest supported Angular versions need a careful read rather than an automatic rule.

The release list shows the cadence for the current line: v22.0.0 for Angular 22 support in August 2026, v21.0.0 for Angular 21 in January 2026 and v19 for Angular 19 in February 2025. The last push to the repository was on 2026-10-19, and the package.json is at version 22.0.1.

The library is MIT licensed and the project is maintained by Yuvraj Chauhan, with funding handled through GitHub Sponsors and a buy-me-a-coffee link.

The newer features: interceptor, top layer overlays and the ng add fix

The What's New section lists what changed recently, and it is worth reading as the current state of the library rather than as a changelog.

The first is the optional HTTP interceptor. Instead of calling the service from every component, you can let the spinner appear and disappear around HTTP requests. The library positions this as optional, and the README has a dedicated section for it, which tells you it is opt-in rather than the default behaviour.

The second is the fix for stacking behind MatDialog and other Angular CDK overlays. The fullscreen spinner now renders in the browser's native top layer through the Popover API, with an opt-out through a usePopover input set to false. That is a real problem with a specific and unglamorous cause. A Material dialog renders in an overlay container, and a fixed-position spinner inside your application cannot paint above it, so a full-screen spinner during a dialog-triggered request used to appear behind the dialog. The Popover API puts the element in the browser's own top layer, above everything the page can draw, which is the correct fix rather than a higher z-index.

The third is the fix to ng add ngx-spinner. The README says it now works correctly for standalone apps, which have been the Angular default since v17, in addition to NgModule-based apps, and that it no longer requires passing --project explicitly.

There is also a rebuilt demo site, which the README describes as a from-scratch redesign with a searchable animation gallery, a live preview stage driving the real ngx-spinner component, a configuration panel covering every option, and a generated-code panel with the HTML template and the TypeScript service usage, with one-click copy and a dark and light theme toggle.

That last item matters more than a demo usually would, because a spinner library is mostly a set of options, and a panel that shows every option with the code it produces is the fastest way to learn the API.

Installing with ng add and how the package is built

Installation is the Angular CLI schematic, one command:

ng add ngx-spinner

The repository shows how that is wired up. The package.json build scripts for the library are:

"build:lib": "ng build ngx-spinner && npm run copy && npm run build:schematics",
"copy": "cp README.md LICENSE.md dist/ngx-spinner/",
"build:schematics": "cd projects/ngx-spinner && npm run build",

So the schematic is a separate workspace project built and shipped alongside the library, which is the standard Angular library layout, and the README and licence are copied into the published package.

The tree follows the modern Angular CLI workspace shape: an angular.json at the root, a projects/ directory holding the library and what appears to be a tester application, tsconfig.json, eslint.config.js, package-lock.json, plus .vscode/ and .editorconfig.

The runtime dependencies are the Angular packages themselves at version 22.1.3, with rxjs at 7.8.1, zone.js at 0.16.2 and tslib, plus core-js. The Angular CDK is present as a development dependency rather than a runtime one, which fits the MatDialog mention in the description: the library interacts with CDK overlays without requiring CDK to be installed in the consuming application.

The engines field is strict about Node: ^22.22.3 || ^24.15.0 || >=26.0.0. That is a much narrower window than most libraries impose, and it comes from the fact that the build and test toolchain is on Angular 22.

Testing is through Karma with Jasmine, with karma-chrome-launcher and coverage reporting through karma-coverage-istanbul-reporter, and there is an e2e script alongside the unit tests.

Using the spinner: named types, the service and custom spinners

The usage sections of the README are organised around three ideas.

The first is selecting a spinner type. More than fifty named spinners are available, and the README has a section on using the spinner type, plus a separate one on using a custom spinner, and a note that explains how the type is resolved when you do not pick one explicitly.

The second is the service, which is how the spinner is shown and hidden programmatically. The API is straightforward in shape: a service you inject, a show call and a hide call, and a component you place in the template for the area that should display the indicator.

The third is the options. The README's table of contents has an Available Options section with subsections for the spinner type, for custom spinners and a NOTE, and there is a separate section listing the available options. The demo's configuration panel covering every option is the place to see the full set at once.

What the interceptor changes is where the show and hide calls come from. Instead of your component deciding that a request is in flight, the interceptor sees the request go out and the response come back and manages the spinner itself. That is the difference between a library that saves you a line in every component and one that changes nothing about how your code is written.

The Popover opt-out is worth noting alongside the options. Setting usePopover to false puts the spinner back into the ordinary stacking context, which is what you want if the application is running in an environment where the Popover API is unavailable, or if a test harness cannot deal with the top layer.

The useful tips section of the README is the one to check when something is not behaving, since the interaction between the spinner, the CDK overlay and the browser top layer is exactly the sort of thing where a configuration detail changes the result.

Browser support and what the Popover approach costs

The README carries a browser support table covering Chrome, Firefox, IE or Edge, Safari and Opera, with the row for each. The Popover API is a relatively recent browser feature, so the table is the place to check whether the top-layer rendering works in the browsers your users have.

That matters more than it might appear, because the Popover fix is what makes the fullscreen spinner work above a Material dialog. On a browser without it, you are back to the original behaviour unless you opt out, and the opt-out does not restore the ability to paint above the dialog.

There is a second cost, which is the one that comes with any fix that changes how an element is rendered. An element promoted to the browser's top layer is no longer in the normal document flow, and it is no longer inside whatever stacking context the application created. That affects things like inherited CSS custom properties, which do not cascade into a top-layer element, and it affects containment and clipping. A spinner with a custom colour set through a CSS variable, for instance, needs that variable to be defined in a scope the top-layer element can still see.

The third point is about the interceptor. An interceptor that shows a spinner for every HTTP request is a simplification, and real applications have requests that should not produce a spinner: a polling request that runs every few seconds, a request that is part of a longer operation already showing its own indicator, a background prefetch. The README describes the interceptor as optional, and if you use it you will need to decide how it treats those cases.

The fourth is the animation approach. The library is written in TypeScript and CSS, and the spinners are CSS animations. That is the right technology for the job, since CSS animations run on the compositor and do not block the main thread, but it also means the animations are constrained by what CSS can express, and the visual identity is CSS rather than a canvas or SVG renderer.

Limits: framework coupling, a strict Node floor and a maintenance-funded model

The limits are visible in the metadata and in the shape of the project.

The first is Angular coupling, which is total. The library depends on Angular core, common, compiler, forms, platform-browser, platform-browser-dynamic and router, and it uses Angular CDK overlays. It is not usable outside Angular, and the version matrix ties it to a specific Angular major.

The second is the Node engine floor. The package requires ^22.22.3 || ^24.15.0 || >=26.0.0, so a project on Node 20 cannot install the current version, and one on Node 22 has to be on a late 22.x patch. That is a consequence of supporting the newest Angular major, and it is a real constraint for CI images that are not on a recent Node.

The third is the version scheme. Unlike most Angular libraries, which publish one major version per Angular major, ngx-spinner publishes a version line per Angular version and requires you to pick the right one. That is friendlier for users on older Angular versions and it means the npm dist-tag for latest is not necessarily what an old project should install. It also means each Angular major needs its own release from the same codebase, which is a maintenance pattern that depends on there being one maintainer with the time to do it.

The fourth is the funding model. The README asks for sponsorship through GitHub Sponsors and a buy-me-a-coffee link, which is normal and worth supporting. The point is that a library with fifty animations, an interceptor, a schematic, a demo site with a live preview and a configuration panel is a substantial amount of surface to maintain, and the version matrix implies continued work across many Angular majors.

The fifth is what the library is not. It is a spinner, and a good one, but it does not do progress reporting, does not handle long-running work with meaningful progress, and does not provide a queue or a counter for concurrent operations. If your application has two requests in flight, the interceptor's show and hide calls have to be arranged so the spinner does not disappear when the first one finishes.

ngx-spinner against a CSS spinner of your own and against a component library

Two comparisons make the choice clearer.

The first is against writing the spinner yourself. A loading indicator is a div with a border, a border-radius, a CSS animation and a rotation. That is twenty lines of CSS and it gives you exactly the look you want, with no dependency and no version to track. The case for a library is the fifty other animations, the service API, the interceptor and the overlay handling.

So the honest framing is that ngx-spinner earns its place when you want the choice and the automation, not when you want a spinner. If your application needs one spinner in one place, a stylesheet is better: less code, no Node version constraint, nothing to upgrade during an Angular major bump. If you want fifty options, a single show and hide service, and an interceptor that drives the indicator from your HTTP layer, the library is a reasonable deal.

The second comparison is against a general component library. Angular Material has its own progress indicator, and a design system library will have one too. The difference in approach is that a general component library gives you one indicator that matches its design language, while ngx-spinner gives you fifty styles that match nothing in particular and are meant to be recognisable as loading states in their own right.

There is also the practical matter of the overlay fix. If your application uses MatDialog and shows a spinner during a dialog-driven request, then the fact that ngx-spinner handles the top layer correctly is worth something on its own, and it is a bug you would otherwise hit and debug yourself.

The practical conclusion is that the decision is about your application's Angular major and your appetite for a dependency that follows Angular's release train closely. The library is well maintained for the current majors and there is a matching release for almost every older one, which is unusual and genuinely useful.

Editorial conclusion

Adopt ngx-spinner if your Angular application needs a loading indicator in several places and you want the HTTP requests to drive it automatically rather than wiring the service into every component. Do not adopt it if the animation set matters more than the plumbing, because the visuals are ordinary CSS and you can write your own. Verify first which library version matches your Angular major, since the project ships a separate release line for each, that the spinner renders in the top layer in the browsers you support, and that the interceptor's behaviour matches how your application reports long-running work that is not an HTTP request.

Frequently asked questions

Official sources

1. License: MIT
2. Napster2210/ngx-spinner on GitHub
3. Project website
4. README
5. Releases