loader-pro

A modern, lightweight, and feature-rich loader package for React and Next.js. Better than react-loader-spinner with multi-style support, text/custom content, comprehensive edge case handling, and zero configuration.

🚀 Features

• ✅ 34+ Loader Types: Spinner, Skeleton, Dots, Progress, Audio, BallTriangle, Bars, Beat, Bounce, Circle, Clip, Clock, Dot, Fade, Grid, Hash, Moon, Pacman, Puff, Pulse, Ring, Rise, Rotate, RotatingSquare, Scale, Segments, Sync, TailSpin, ThreeDots, Triangle, Wave, Vortex, Orbit, Atom
• ✅ Text/Custom Content Support: All loaders support labels and children
• ✅ Multi-Style Support: Tailwind CSS, CSS Modules, External CSS (CSS v4), CSS-in-JS
• ✅ Lightweight: < 5KB gzipped (core), < 10KB with styles
• ✅ Zero Dependencies: Only React (no clsx, no external libs)
• ✅ Zero Configuration: Works immediately after installation
• ✅ TypeScript: Full type definitions included
• ✅ Edge Cases Handled: Null/undefined, invalid values, SSR, RTL, reduced motion, accessibility
• ✅ Next.js Optimized: Built for Next.js App Router with SSR support
• ✅ Performance: GPU-accelerated animations, optimized re-renders

📦 Installation

npm install loader-pro
# or
yarn add loader-pro
# or
pnpm add loader-pro

That's it! No additional setup required. Works immediately.

🎯 Quick Start

import { 
  Spinner, Skeleton, Dots, Progress,
  Audio, BallTriangle, Bars, Beat, Bounce,
  Circle, Clip, Clock, Dot, Fade, Grid,
  Hash, Moon, Pacman, Puff, Pulse, Ring,
  Rise, Rotate, RotatingSquare, Scale, Sync,
  TailSpin, ThreeDots, Triangle, Wave,
  Vortex, Orbit, Atom
} from 'loader-pro';

function MyComponent() {
  return (
    <div>
      <Spinner />
      <Audio size="large" />
      <Pacman color="#ff6b6b" />
      <Atom size="medium" />
      {/* ... and 29+ more loaders! */}
    </div>
  );
}

📚 Usage Examples

Basic Usage (Default Styles)

import { Spinner } from 'loader-pro';
import 'loader-pro/styles.css'; // Optional: import default styles

<Spinner size="large" color="#0070f3" />

With Tailwind CSS

import { Spinner } from 'loader-pro';

<Spinner 
  className="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-500"
/>

With External CSS (CSS v4)

import { Spinner } from 'loader-pro';
import './my-custom-loaders.css';

<Spinner className="my-custom-spinner" />

With Text/Labels

import { Spinner, Progress, Dots } from 'loader-pro';

// Spinner with label
<Spinner size="large" label="Loading..." />

// Spinner with custom children
<Spinner size="medium">
  <span className="ml-2">Processing...</span>
</Spinner>

// Progress with custom label
<Progress 
  value={60} 
  max={100}
  label="60% Complete"
  showLabel={true}
/>

// Progress with custom formatter
<Progress 
  value={75} 
  max={100}
  formatLabel={(value, max) => `${value}/${max} files`}
/>

// Dots with text
<Dots count={3} label="Loading data..." />

Mixed Approach

import { Spinner } from 'loader-pro';

<Spinner 
  size="large"
  className="animate-spin" // Tailwind
  style={{ borderColor: '#0070f3' }} // Inline style
  label="Loading..." // Text
/>

🎨 Components

Spinner

Circular spinner with multiple variants.

<Spinner 
  size="medium" // 'small' | 'medium' | 'large' | number
  color="#0070f3"
  variant="default" // 'default' | 'pulse' | 'ring' | 'bars' | 'grid'
  speed={1}
  label="Loading..."
  className="..."
  style={{...}}
/>

Props:

• size: 'small' | 'medium' | 'large' | number - Size of spinner
• color: string - Color of spinner
• variant: 'default' | 'pulse' | 'ring' | 'bars' | 'grid' - Spinner variant
• speed: number - Animation speed multiplier
• label: string - Optional label text
• children: ReactNode - Custom content
• className: string - Additional CSS classes
• style: CSSProperties - Inline styles
• aria-label: string - Accessibility label

Skeleton

Placeholder content loader.

<Skeleton 
  width="200px"
  height="20px"
  variant="text" // 'text' | 'circle' | 'rectangle' | 'custom'
  count={1}
  rounded={false}
  animated={true}
  baseColor="#f0f0f0"
  highlightColor="#e0e0e0"
  className="..."
/>

Props:

• width: string | number - Width of skeleton
• height: string | number - Height of skeleton
• variant: 'text' | 'circle' | 'rectangle' | 'custom' - Shape variant
• count: number - Number of skeleton items
• rounded: boolean - Rounded corners
• animated: boolean - Enable animation
• baseColor: string - Base color
• highlightColor: string - Highlight color
• children: ReactNode - Content to wrap
• className: string - Additional CSS classes
• style: CSSProperties - Inline styles

Dots

Animated dots loader.

<Dots 
  count={3}
  size="medium" // 'small' | 'medium' | 'large' | number
  color="#0070f3"
  speed={1}
  variant="bounce" // 'bounce' | 'pulse' | 'wave'
  label="Loading..."
  className="..."
/>

Props:

• count: number - Number of dots (1-10)
• size: 'small' | 'medium' | 'large' | number - Size of dots
• color: string - Color of dots
• speed: number - Animation speed multiplier
• variant: 'bounce' | 'pulse' | 'wave' - Animation variant
• label: string - Optional label text
• children: ReactNode - Custom content
• className: string - Additional CSS classes
• style: CSSProperties - Inline styles

Progress

Linear or circular progress bar.

<Progress 
  value={60}
  max={100}
  variant="linear" // 'linear' | 'circular'
  color="#0070f3"
  showLabel={false}
  label="60%"
  formatLabel={(value, max) => `${value}/${max}`}
  size="medium"
  className="..."
/>

Props:

• value: number - Current value (undefined for indeterminate)
• max: number - Maximum value (default: 100)
• variant: 'linear' | 'circular' - Progress variant
• color: string - Progress color
• showLabel: boolean - Show percentage label
• label: string - Custom label text
• formatLabel: (value: number, max: number) => string - Custom label formatter
• size: 'small' | 'medium' | 'large' | number - Size (for circular)
• children: ReactNode - Custom content
• className: string - Additional CSS classes
• style: CSSProperties - Inline styles

📋 All 33+ Loaders

Core Loaders

• Spinner - Circular spinner with 5 variants
• Skeleton - Placeholder content loader
• Dots - Animated dots (3 variants)
• Progress - Linear and circular progress bars

Spinner Loaders

• Audio - Audio waveform animation
• BallTriangle - Three balls in triangle formation
• Bars - Horizontal bars animation
• Beat - Pulsing dots
• Bounce - Bouncing circle
• Circle - Multiple rotating circles
• Clip - Circular clip loader
• Clock - Clock with hour and minute hands
• Dot - Single pulsing dot
• Fade - Fading bars
• Grid - 3x3 grid of animated dots
• Hash - Hash symbol animation
• Moon - Crescent moon loader
• Pacman - Pac-man style loader
• Puff - Expanding circles
• Pulse - Pulsing circle
• Ring - Spinning ring
• Rise - Rising bars
• Rotate - Rotating squares
• RotatingSquare - Single rotating square
• Scale - Scaling bars
• Sync - Syncing dots
• TailSpin - Tail spinning ring
• ThreeDots - Three bouncing dots
• Triangle - Rotating triangles
• Wave - Wave animation
• Vortex - Vortex spinning rings
• Orbit - Orbiting dots
• Atom - Atom with orbiting electrons

🆚 Comparison with react-loader-spinner

| Feature | react-loader-spinner | loader-pro | |---------|---------------------|---------------------| | Loader Count | ~35 spinners | ✅ 33+ loaders (more variety) | | Bundle Size | ~15KB | < 5KB (core) | | Text Support | Limited | ✅ Full support | | Edge Cases | Basic | ✅ Comprehensive | | Styling | Fixed CSS | ✅ Multi-style (Tailwind, CSS v4, etc.) | | Loader Types | Spinners only | ✅ Spinner + Skeleton + Progress + Dots + 29 more | | Dependencies | Some deps | ✅ Zero (except React) | | Performance | Good | ✅ Optimized (GPU, memo) | | Next.js | Generic | ✅ Native optimized | | Zero Config | Works | ✅ Works + better DX |

🛡️ Edge Cases Handled

• ✅ Null/undefined props with sensible defaults
• ✅ Invalid values (negative, NaN, out of range)
• ✅ SSR hydration safety
• ✅ RTL language support
• ✅ Reduced motion preferences (prefers-reduced-motion)
• ✅ Full accessibility (ARIA, keyboard navigation)
• ✅ Dark mode support
• ✅ Memory leak prevention

🎨 Styling

Tailwind CSS

<Spinner className="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-500" />

CSS Modules

import styles from './MyComponent.module.css';
<Spinner className={styles.customSpinner} />

External CSS (CSS v4)

import './my-loaders.css';
<Spinner className="my-spinner" />

CSS Variables

All components support CSS variables for theming:

:root {
  --loader-spinner-color: #0070f3;
  --loader-skeleton-base: #f0f0f0;
  --loader-dots-color: #0070f3;
  --loader-progress-color: #0070f3;
}

📖 TypeScript

Full TypeScript support with exported types:

import { Spinner, SpinnerProps } from 'loader-pro';

const props: SpinnerProps = {
  size: 'large',
  color: '#0070f3',
};

🚀 Performance

• Bundle Size: < 5KB gzipped (core)
• GPU-Accelerated: Animations use CSS transforms
• Optimized Re-renders: React.memo where appropriate
• Tree-Shakeable: Only import what you use
• Lazy Loading: Support for code splitting

📝 License

MIT

🤝 Contributing

Contributions welcome! Please open an issue or PR.

Made with ❤️ for React and Next.js developers