universal-spinner

A lightweight, reusable SVG loading spinner for modern web applications.

• Zero runtime dependencies
• Framework-agnostic
• SVG-based
• Configurable size and color
• Multiple spinner styles
• Works with React, Angular, Vue, and vanilla JavaScript

Installation

Install the package from npm:

npm install universal-spinner

Import the spinner and stylesheet:

import { createSpinner } from "universal-spinner";
import "universal-spinner/styles.css";

Basic Usage

Create a spinner, mount it to a container, and start it:

const spinner = createSpinner({
  size: 32,
  color: "royalblue",
});

spinner.mount(container);
spinner.start();

Stop the spinner when loading is complete:

spinner.stop();

Variants

Choose a spinner using the variant option.

Pulse

The default three-dot loading animation.

createSpinner({
  variant: "pulse",
});

Circle

A circular rotating dot loader.

createSpinner({
  variant: "circle",
});

Wave

A horizontal wave-style loading animation.

createSpinner({
  variant: "wave",
});

Bounce

Three independently moving circles with configurable colors.

createSpinner({
  variant: "bounce",
  colors: ["red", "green", "blue"],
});

Each circle can have its own color.

Circle 1 → red
Circle 2 → green
Circle 3 → blue

Yin-Yang

A rotating Yin-Yang style loader.

createSpinner({
  variant: "yinyang",
});

Configuration

Size

Numbers are treated as pixels:

createSpinner({
  size: 48,
});

CSS size values are also supported:

createSpinner({
  size: "2rem",
});

Color

Use any valid CSS color:

createSpinner({
  color: "royalblue",
});

createSpinner({
  color: "#6366f1",
});

CSS variables are also supported:

createSpinner({
  color: "var(--primary-color)",
});

Bounce Colors

The bounce variant supports three independently configurable colors:

createSpinner({
  variant: "bounce",
  colors: [
    "#ef4444",
    "#22c55e",
    "#3b82f6",
  ],
});

If colors is not provided, the normal color option is used.

Spinner Controls

Start

spinner.start();

Starts the spinner.

Stop

spinner.stop();

Stops the spinner.

Mount

spinner.mount(container);

Adds the spinner to a DOM element.

Unmount

spinner.unmount();

Removes the spinner from the DOM.

Check Running State

spinner.isRunning();

Returns whether the spinner is currently running.

Framework Support

universal-spinner is framework-agnostic and works with:

• Vanilla JavaScript / TypeScript
• React
• Angular
• Vue
• Other frameworks that can access a DOM element

No framework-specific package or adapter is required.

React

Use a ref to provide the DOM element to spinner.mount().

Angular

Use an element reference such as ElementRef and pass its native element to spinner.mount().

Vue

Use a template ref and pass the referenced DOM element to spinner.mount().

The spinner itself does not depend on React, Angular, Vue, or any other framework.

CSS

Import the stylesheet once in your application:

import "universal-spinner/styles.css";

The library does not automatically inject CSS into the document.

Available Variants

| Variant | Description | |---|---| | pulse | Three-dot sequential pulse | | circle | Circular rotating dots | | wave | Horizontal wave animation | | bounce | Three independently moving colored circles | | yinyang | Rotating Yin-Yang loader |

The default variant is pulse.

License

MIT