@pmeig/ngb-spinner

A powerful Angular library that provides Bootstrap-styled loading spinners with customizable shapes, sizes, and colors for indicating loading states in your applications.

Installation

  npm install @pmeig/ngb-spinner

Features

• 🎯 SpinnerMaterial Directive - Lightweight spinner directive with Bootstrap styling
• 📦 Shape Variants - Border and grow animation types
• 🔄 Size Options - Small, default, and large spinner sizes
• ✨ Color Theming - Bootstrap color variants and custom color support
• 🎨 CSS Integration - Full Bootstrap 5.3.3 spinner compatibility
• 🚀 Angular 21.2.0 support with signals
• 📱 Responsive Design - Scalable spinners for all screen sizes
• ♿ Accessibility - add role="status" and a visually hidden text yourself
• 🛠️ Flexible Implementation - Easy integration with existing elements

Usage

Import the Module

import { SpinnerMaterial } from '@pmeig/ngb-spinner';
@Component({
imports: [SpinnerMaterial],
// ...
})
export class MyComponent { }

Basic Border Spinner

<spinner></spinner>

Grow Spinner

<spinner shape="grow"></spinner>

Colored Spinners

<spinner color="primary"></spinner>
<!-- accessible: -->
<spinner color="primary" role="status"><span class="visually-hidden">Loading...</span></spinner>
<spinner color="success"></spinner>
<spinner color="danger"></spinner>
<spinner color="warning"></spinner>
<spinner color="info"></spinner>

Different Sizes

<!-- Small Spinner -->
<spinner size="sm" color="primary"></spinner>

<!-- Default Spinner -->
<spinner color="secondary"></spinner>

<!-- Large Spinner -->
<spinner size="lg" color="success"></spinner> <!-- spinner-border-lg: not styled by Bootstrap -->

Custom Colors

<!-- Hex Color -->
<spinner color="#ff6b35"></spinner>

<!-- RGB Color -->
<spinner color="rgb(255, 107, 53)"></spinner>

<!-- CSS Variable -->
<spinner color="var(--custom-color)"></spinner>

Loading States in Buttons

<!-- as in Bootstrap: the spinner is decorative (aria-hidden), the text carries role="status" -->
<button color="primary" [disabled]="isLoading">
  @if (isLoading) {
    <spinner size="sm" aria-hidden="true" class="me-2"></spinner>
    <span role="status">Loading...</span>
  } @else {
    Submit
  }
</button>

Inline Loading Indicators

<div class="d-flex align-items-center">
  <spinner size="sm" color="primary" class="me-2"></spinner>
  <span>Loading data...</span>
</div>

Center Loading Overlay

<div class="text-center py-5">
  <spinner size="lg" color="primary"></spinner>
  <div class="mt-3">
    <h5>Loading...</h5>
    <p class="text-muted">Please wait while we fetch your data.</p>
  </div>
</div>

API Reference

Spinner Directive Options

| Property | Type | Default | Description | |----------|------|---------|-------------| | shape | 'border' \| 'grow' | 'border' | Animation type - rotating border or pulsing grow effect | | size | 'sm' \| 'lg' | undefined | Spinner size variant | | color | ColorConfig \| ColorAttribute | {style: ''} | Spinner color configuration |

Shape Options

• Border: shape="border" - Rotating border spinner (default)
• Grow: shape="grow" - Pulsing/scaling spinner effect

Size Options

• Small: size="sm" - Compact spinner for inline use
• Default: No size attribute - Standard spinner size
• Large: size="lg" - no Bootstrap style (see Bootstrap Classes Support)

Color Configuration

• Bootstrap Colors: primary, secondary, success, danger, warning, info, light, dark
• Custom CSS Colors: Hex (#ff0000), RGB (rgb(255,0,0)), HSL, CSS variables
• CSS Classes: Custom text color classes

How It Works

Spinner Implementation

The spinner directive automatically:

1. Class Application: Applies appropriate Bootstrap spinner classes
2. Size Management: Handles size variant styling
3. Color Processing: Manages color through CSS classes or inline styles
4. Animation Control: Provides smooth, hardware-accelerated animations
5. Accessibility: adds no ARIA attribute: put role="status" and a <span class="visually-hidden">Loading...</span> inside yourself

Performance Considerations

• Lightweight: Minimal DOM manipulation and CSS
• Hardware Acceleration: Uses CSS transforms for smooth animations
• Conditional Rendering: Only renders when needed to save resources

Bootstrap Classes Support

This library generates and works with standard Bootstrap 5 spinner classes:

• spinner-border - Rotating border spinner
• spinner-grow - Growing/pulsing spinner
• spinner-border-sm, spinner-grow-sm - Small size variants
• spinner-border-lg, spinner-grow-lg - written for size="lg", but Bootstrap has no such class: a large spinner needs your own CSS (or style="width: 3rem; height: 3rem"), as the Bootstrap docs do
• text-primary, text-success, etc. - Text color classes

Dependencies

• Angular: >=21.2
• @angular/common: >=21.2
• @pmeig/ngb-core: ^2.0.0
• tslib: ^2.3.0

Compatibility

• Angular: 21.2
• Bootstrap: 5.3.3+
• TypeScript: 5.8.3+
• Modern browsers (Chrome, Firefox, Safari, Edge)

Troubleshooting

Common Issues

Spinner not appearing

• Ensure the spinner directive is properly imported
• Check that Bootstrap CSS is loaded
• Verify that the element is not hidden by CSS

Animation not smooth

• Ensure hardware acceleration is enabled in the browser
• Check for conflicting CSS animations
• Verify that the element has proper positioning

Color not applying

• Check that the color name is a valid Bootstrap variant
• For custom colors, ensure proper CSS color syntax
• Verify that text color classes are not being overridden

Size not working correctly

• Confirm that Bootstrap size classes are available
• Check for conflicting CSS that might override dimensions
• Ensure proper spacing around sized spinners

Accessibility issues

• Add appropriate ARIA labels for screen readers
• Ensure sufficient color contrast for visibility
• Provide text alternatives for loading states

License

This project is licensed under the MIT License.

Support

For issues and questions, please open an issue on the GitHub repository.

Fixed in 2.0.1

• A CSS color (color="#ff6b35", color="white") is painted: 2.0.0 threw Cannot read properties of undefined (the RGB value of a non-RGB color is '', and '' ?? style kept '').