satyam-animated-spinner

A beautiful, customizable animated spinner component with multiple animation styles. Perfect for loading states in any JavaScript/TypeScript project.

✨ Features

• 🎨 5 Beautiful Animation Styles: Circle, Dots, Bars, Ring, and Pulse
• 🎯 Fully Customizable: Size, color, speed, and overlay options
• 📦 Lightweight: Zero dependencies, minimal bundle size
• 💪 TypeScript Support: Full type definitions included
• 🌐 Framework Agnostic: Works with vanilla JS, React, Vue, Angular, and more
• 🚀 Easy to Use: Simple API with sensible defaults

📦 Installation

npm install satyam-animated-spinner

Important: Don't forget to import the CSS file in your project!

import 'satyam-animated-spinner/dist/index.esm.css';

🚀 Quick Start

Basic Usage

import { AnimatedSpinner } from 'satyam-animated-spinner';
import 'satyam-animated-spinner/dist/index.esm.css';

// Create a spinner
const spinner = new AnimatedSpinner();

// Show it
spinner.show();

// Hide it when done
setTimeout(() => {
  spinner.hide();
}, 2000);

With Custom Options

import { AnimatedSpinner } from 'satyam-animated-spinner';
import 'satyam-animated-spinner/dist/index.esm.css';

const spinner = new AnimatedSpinner({
  type: 'dots',           // Animation type
  size: 60,               // Size in pixels
  color: '#ff6b6b',       // Primary color
  speed: 1.5,             // Animation speed in seconds
  overlay: true,          // Show overlay background
  overlayColor: 'rgba(0, 0, 0, 0.7)'
});

spinner.show();

🎨 Spinner Types

The package includes 5 different animation styles:

• circle - Classic rotating circle with gap (default)
• dots - Three pulsing dots
• bars - Three bouncing bars
• ring - Rotating ring with pulse effect
• pulse - Single pulsing circle

📖 API Reference

Constructor Options

interface SpinnerOptions {
  type?: 'circle' | 'dots' | 'bars' | 'ring' | 'pulse';  // Default: 'circle'
  size?: number;                    // Default: 40
  color?: string;                   // Default: '#3b82f6'
  speed?: number;                   // Default: 1
  container?: HTMLElement;          // Default: document.body
  overlay?: boolean;                // Default: true
  overlayColor?: string;            // Default: 'rgba(0, 0, 0, 0.5)'
  className?: string;               // Optional custom CSS class
}

Methods

show()

Display the spinner.

spinner.show();

hide()

Hide the spinner with a fade-out animation.

spinner.hide();

setType(type)

Change the spinner animation type.

spinner.setType('dots');

setColor(color)

Update the spinner color.

spinner.setColor('#ff6b6b');

setSize(size)

Update the spinner size.

spinner.setSize(60);

setSpeed(speed)

Update the animation speed (in seconds).

spinner.setSpeed(2);

isShowing()

Check if the spinner is currently visible.

if (spinner.isShowing()) {
  console.log('Spinner is visible');
}

destroy()

Clean up and remove the spinner.

spinner.destroy();

💡 Usage Examples

With Async Operations

import { AnimatedSpinner } from 'satyam-animated-spinner';
import 'satyam-animated-spinner/dist/index.esm.css';

const spinner = new AnimatedSpinner({ type: 'ring' });

async function fetchData() {
  spinner.show();
  
  try {
    const response = await fetch('https://api.example.com/data');
    const data = await response.json();
    return data;
  } finally {
    spinner.hide();
  }
}

Multiple Spinners

import { AnimatedSpinner } from 'satyam-animated-spinner';
import 'satyam-animated-spinner/dist/index.esm.css';

// Full-page spinner
const pageSpinner = new AnimatedSpinner({
  type: 'circle',
  overlay: true
});

// Inline spinner in a specific container
const containerSpinner = new AnimatedSpinner({
  type: 'dots',
  size: 30,
  overlay: false,
  container: document.getElementById('my-container')
});

React Integration

import { useEffect, useRef } from 'react';
import { AnimatedSpinner } from 'satyam-animated-spinner';
import 'satyam-animated-spinner/dist/index.esm.css';

function MyComponent() {
  const spinnerRef = useRef(null);

  useEffect(() => {
    spinnerRef.current = new AnimatedSpinner({
      type: 'pulse',
      color: '#3b82f6'
    });

    return () => {
      spinnerRef.current?.destroy();
    };
  }, []);

  const handleClick = async () => {
    spinnerRef.current?.show();
    await someAsyncOperation();
    spinnerRef.current?.hide();
  };

  return <button onClick={handleClick}>Load Data</button>;
}

Vue Integration

<template>
  <button @click="loadData">Load Data</button>
</template>

<script>
import { AnimatedSpinner } from 'satyam-animated-spinner';
import 'satyam-animated-spinner/dist/index.esm.css';

export default {
  data() {
    return {
      spinner: null
    };
  },
  mounted() {
    this.spinner = new AnimatedSpinner({
      type: 'bars',
      color: '#10b981'
    });
  },
  beforeUnmount() {
    this.spinner?.destroy();
  },
  methods: {
    async loadData() {
      this.spinner.show();
      await this.fetchData();
      this.spinner.hide();
    }
  }
};
</script>

🎨 Customization

Custom Colors

// Solid color
const spinner = new AnimatedSpinner({
  color: '#ff6b6b'
});

// Use CSS variables
const spinner = new AnimatedSpinner({
  color: 'var(--primary-color)'
});

Custom Container

// Show spinner in a specific element
const spinner = new AnimatedSpinner({
  container: document.getElementById('loading-area'),
  overlay: false
});

Custom Styling

const spinner = new AnimatedSpinner({
  className: 'my-custom-spinner'
});

Then in your CSS:

.my-custom-spinner {
  /* Your custom styles */
  filter: drop-shadow(0 0 10px rgba(59, 130, 246, 0.5));
}

📄 License

MIT © satyam

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🐛 Issues

If you find a bug or have a feature request, please open an issue on GitHub.