@versini/ui-spinner

A lightweight and accessible React spinner component built with TypeScript and TailwindCSS.

The Spinner component provides visual loading indicators with multiple styles and theme support. It's designed to be accessible and follows best practices for loading states.

Table of Contents

• Features
• Installation
• Usage
• API

Features

• 🎯 Multiple Types: Circle and dots spinner animations
• ♿ Accessible: Includes proper ARIA roles for screen readers
• 🎨 Customizable: Multiple themes and styling options
• 🌲 Tree-shakeable: Lightweight and optimized for bundle size
• 🔧 TypeScript: Fully typed with comprehensive prop definitions
• 🎭 Theme Support: Built-in support for light, dark, and system themes

Installation

npm install @versini/ui-spinner

Note: This component requires TailwindCSS and the @versini/ui-styles plugin for proper styling. See the installation documentation for complete setup instructions.

Usage

Basic Spinner

import { Spinner } from "@versini/ui-spinner";

function App() {
  return (
    <div>
      <p>Loading...</p>
      <Spinner />
    </div>
  );
}

Dots Spinner

import { Spinner } from "@versini/ui-spinner";

function App() {
  return (
    <div>
      <p>Processing...</p>
      <Spinner type="dots" />
    </div>
  );
}

Different Themes

import { Spinner } from "@versini/ui-spinner";

function App() {
  return (
    <div className="space-x-4">
      <Spinner mode="light" />
      <Spinner mode="dark" />
      <Spinner mode="system" />
    </div>
  );
}

Custom Styling

import { Spinner } from "@versini/ui-spinner";
import { useRef } from "react";

function App() {
  const spinnerRef = useRef<HTMLDivElement>(null);

  return (
    <Spinner
      ref={spinnerRef}
      className="text-blue-500 w-12 h-12"
      mode="light"
    />
  );
}

API

Spinner Props

| Prop | Type | Default | Description | | ---------- | ----------------------------------------------- | ---------- | ------------------------------------------- | | type | "circle" \| "dots" | "circle" | The type of spinner to render | | mode | "dark" \| "light" \| "system" \| "alt-system" | "system" | The mode of spinner (controls theme/color) | | className | string | - | CSS class(es) to add to the spinner element | | spinnerRef | React.RefObject<HTMLDivElement> | - | A ref to the spinner element |

Examples

Loading States

import { Spinner } from "@versini/ui-spinner";
import { useState, useEffect } from "react";

function LoadingExample() {
  const [loading, setLoading] = useState(true);
  const [data, setData] = useState(null);

  useEffect(() => {
    // Simulate API call
    setTimeout(() => {
      setData("Loaded data");
      setLoading(false);
    }, 2000);
  }, []);

  if (loading) {
    return (
      <div className="flex items-center space-x-2">
        <Spinner />
        <span>Loading data...</span>
      </div>
    );
  }

  return <div>Data: {data}</div>;
}

Different Spinner Types

import { Spinner } from "@versini/ui-spinner";

function SpinnerTypesExample() {
  return (
    <div className="space-y-4">
      <div className="flex items-center space-x-2">
        <Spinner type="circle" />
        <span>Circle spinner</span>
      </div>

      <div className="flex items-center space-x-2">
        <Spinner type="dots" />
        <span>Dots spinner</span>
      </div>
    </div>
  );
}

Inline Loading

import { Spinner } from "@versini/ui-spinner";

function InlineLoadingExample() {
  return (
    <div className="space-y-2">
      <p>
        Saving changes <Spinner className="inline ml-1 w-4 h-4" />
      </p>

      <button className="flex items-center space-x-2" disabled>
        <Spinner className="w-4 h-4" />
        <span>Processing...</span>
      </button>
    </div>
  );
}

Custom Sizes and Colors

import { Spinner } from "@versini/ui-spinner";

function CustomSpinnerExample() {
  return (
    <div className="space-y-4">
      {/* Small spinner */}
      <Spinner className="w-4 h-4" />

      {/* Medium spinner (default) */}
      <Spinner />

      {/* Large spinner */}
      <Spinner className="w-12 h-12" />

      {/* Custom color */}
      <Spinner className="text-red-500" mode="light" />

      {/* Thick border */}
      <Spinner className="border-8" />
    </div>
  );
}

Accessible Loading

import { Spinner } from "@versini/ui-spinner";

function AccessibleLoadingExample() {
  return (
    <div>
      {/* The spinner automatically includes role="status" for accessibility */}
      <div aria-live="polite" aria-busy="true">
        <Spinner />
        <span className="sr-only">Loading content, please wait...</span>
      </div>
    </div>
  );
}