ngxsmk-button-spinner

A tiny Angular 17+ directive that adds a loading spinner to any existing <button> — no component swap and no global stylesheet required.

• ✅ Drop-in attribute: [ngxsmkButtonSpinner]="loading"

• ✅ Two display modes:

  • Inline (default): spinner appears after the text with a small gap
  • Overlay (centered): set [ngxsmkButtonSpinnerHideLabel]="true" to hide text and center the spinner

• ✅ Theming via CSS variables (bind directly in the template)

• ✅ A11y-friendly (role="status", configurable aria-label)

• ✅ Strict TypeScript & SSR-safe

Screenshot

Install

  npm i ngxsmk-button-spinner

Peer deps: @angular/core@>=17, @angular/common@>=17.

Quick start

// Any standalone component
import { Component, signal } from '@angular/core';
import { NgxSmkButtonSpinnerDirective } from 'ngxsmk-button-spinner';

@Component({
  selector: 'demo',
  standalone: true,
  imports: [NgxSmkButtonSpinnerDirective],
  template: `
    <button [ngxsmkButtonSpinner]="saving()" (click)="save()">
      Save
    </button>
  `
})
export class DemoComponent {
  saving = signal(false);
  save() {
    this.saving.set(true);
    setTimeout(() => this.saving.set(false), 1500);
  }
}

That’s it — no stylesheet import needed.

API

Directive Inputs

<button
  [ngxsmkButtonSpinner]="loading"
  [ngxsmkButtonSpinnerHideLabel]="true"           <!-- optional: overlay mode -->
  [ngxsmkButtonSpinnerOptions]="{ ariaLabel: 'Saving' }"
>
  Save
</button>

| Input | Type | Default | Description | | ------------------------------ | ------------------------ | -------------------------- | ------------------------------------------------------------------------ | | ngxsmkButtonSpinner | boolean | false | When true, disables the button and shows the spinner. | | ngxsmkButtonSpinnerHideLabel | boolean | false | If true, hides text and centers spinner over the button (overlay). | | ngxsmkButtonSpinnerOptions | { ariaLabel?: string } | { ariaLabel: 'Loading' } | A11y label for the spinner. |

Theming (recommended): bind CSS variables directly

Customize per button by binding these CSS variables. They update reactively — no restarts, no object cloning.

Supported variables (bind any subset):

• --ngxsmk-color (e.g. #0ea5e9 or currentColor)
• --ngxsmk-track (spinner trail color, default transparent)
• --ngxsmk-thickness (e.g. 2px)
• --ngxsmk-size (e.g. 20px, 1.2em)
• --ngxsmk-speed (e.g. 700ms)

Inline example

<button
  [ngxsmkButtonSpinner]="loading"
  [style.--ngxsmk-color]="'#0ea5e9'"
  [style.--ngxsmk-thickness]="'1px'"
  [style.--ngxsmk-size]="'60px'"
  [style.--ngxsmk-speed]="'1500ms'"
>
  Save
</button>

Overlay example (centered, text hidden)

<button
  [ngxsmkButtonSpinner]="loading"
  [ngxsmkButtonSpinnerHideLabel]="true"
  [style.--ngxsmk-color]="'#0ea5e9'"
  [style.--ngxsmk-thickness]="'8px'"
  [style.--ngxsmk-size]="'20px'"
  [style.--ngxsmk-speed]="'500ms'"
>
  Save
</button>

Tip: You can also set these variables in component CSS:

.primary-btn {
  --ngxsmk-color: #2563eb;
  --ngxsmk-thickness: 3px;
  --ngxsmk-size: 22px;
  --ngxsmk-speed: 450ms;
}

Examples

1) Minimal (inline spinner after text)

<button [ngxsmkButtonSpinner]="loading">Submit</button>

2) Overlay (centered) spinner, hide text while loading

<button [ngxsmkButtonSpinner]="loading" [ngxsmkButtonSpinnerHideLabel]="true">
  Save
</button>

3) Custom brand + thicker border + bigger size (via CSS vars)

<button
  [ngxsmkButtonSpinner]="loading"
  class="primary-btn"
  [style.--ngxsmk-color]="'#2563eb'"
  [style.--ngxsmk-thickness]="'3px'"
  [style.--ngxsmk-size]="'22px'"
>
  Publish
</button>

4) Faster spin + size in em

<button
  [ngxsmkButtonSpinner]="loading"
  [style.--ngxsmk-speed]="'450ms'"
  [style.--ngxsmk-size]="'1.4em'"
>
  Sync
</button>

Accessibility

• Spinner element uses role="status" and aria-label (default "Loading").
• The directive sets disabled on the button while loading.
• If you hide the label (overlay mode), screen readers still get the status via the spinner’s aria label.

SSR / hydration

This directive avoids DOM APIs on the server. Spinner elements and the small <style> tag are injected only in the browser after view init. For best UX, toggle loading in response to user actions or browser-only effects.

Troubleshooting

• ReferenceError: document is not defined Ensure you’re using the latest directive: it guards DOM access with PLATFORM_ID and only injects styles in the browser.

• TS2532: Object is possibly 'undefined' The directive is strict-mode safe. If you modified it, null‑check optional fields before use.

• TS5076: && and ?? cannot be mixed Parenthesize or simplify. Example: const keep = theme?.keepLabel ?? false;

• Spinner not visible In overlay mode the label is hidden via a wrapper (visibility: hidden) while the spinner is centered in an overlay box. Ensure your button isn’t applying overflow: hidden in a way that clips the overlay.

Public API

// public-api.ts
export * from './lib/button-spinner.directive';
export * from './lib/types';

Types

export interface NgxSmkButtonSpinnerOptions {
  ariaLabel?: string;
}

export interface NgxSmkButtonSpinnerTheme {
  color?: string;
  trackColor?: string;
  thickness?: string;
  size?: string;
  speedMs?: number;
}

Versioning & support

• Supports Angular 17+ (standalone).
• Semantic versioning. Breaking changes (if any) will bump the major.

License

MIT