Skip to content

Premium React Loaders - A comprehensive collection of premium, production-ready loading components for React applications. Built with TypeScript and Tailwind CSS for maximum flexibility and customization.

License

Notifications You must be signed in to change notification settings

ishansasika/premium-react-loaders

Repository files navigation

Premium React Loaders

A comprehensive collection of 50+ premium, production-ready loading components for React applications. Built with TypeScript and custom CSS for maximum flexibility and zero configuration.

npm version License: MIT

Demo

🚀 Interactive Demo - Playground with live controls and component customization

📚 Storybook Documentation - Detailed component documentation and examples

See all 50+ components in action with interactive examples and customization options.

Features

  • 50+ Premium Components across 15 categories (Skeleton, Spinner, Progress, Pulse, Overlay, Button, Status, Transition, Shimmer, Orbit, Bounce, Infinity, Text, 3D, Smart)
  • 6 Powerful Hooks - useLoader, useEnhancedLoader, useLoadingOrchestrator, useLoadingAnalytics, useSmartLoader, useTheme ✨ New in v3.1.0
  • 3D Loaders - Immersive 3D animations with CSS transforms ✨ New in v3.1.0
  • Smart Components - Context-aware skeletons and form field loaders ✨ New in v3.1.0
  • Accessibility First - LiveRegion component and announcement system ✨ New in v3.1.0
  • Global Theming - ThemeProvider for app-wide customization ✨ New in v2.1.0
  • Smart Loading UX - useLoader hook with delay, minDuration, and autoHide ✨ New in v2.1.0
  • Enhanced CSS Variables - Comprehensive theming with dark mode support ✨ New in v2.1.0
  • Zero Configuration - No Tailwind or build setup required ✨ New in v2.0.0
  • Tiny Bundle Size - 70% smaller CSS (6.27 KB → 1.64 KB gzipped) ✨ New in v2.0.0
  • Zero Runtime Dependencies - No external dependencies needed ✨ New in v2.0.0
  • Size Presets - Easy sizing with xs, sm, md, lg, xl presets
  • Reduced Motion Support - Respects prefers-reduced-motion for accessibility
  • Animation Direction Control - Reverse animations with reverse prop
  • Full TypeScript Support with exported type definitions
  • Tree-shakeable - only bundle what you use
  • Accessible - built with ARIA labels and best practices
  • Performant - hardware-accelerated CSS animations (60fps)
  • Customizable - multiple ways to style components

Installation

npm install premium-react-loaders

Peer Dependencies

This library only requires React:

npm install react react-dom

Note: v2.0.0+ no longer requires Tailwind CSS! See Migration Guide below.

Setup

Import the styles in your main entry file (e.g., main.tsx or App.tsx):

import 'premium-react-loaders/styles';

That's it! No Tailwind configuration or additional setup needed.

Optional: Global Theming (v2.1.0+)

Wrap your app with ThemeProvider to customize all loaders globally:

import { ThemeProvider } from 'premium-react-loaders';

function App() {
  return (
    <ThemeProvider
      theme={{
        primaryColor: '#8b5cf6',
        secondaryColor: '#ec4899',
        defaultSize: 'lg',
        defaultSpeed: 'fast',
      }}
    >
      <YourApp />
    </ThemeProvider>
  );
}

Quick Start

import {
  Skeleton,
  SkeletonCard,
  SpinnerCircle,
  ProgressBar,
  PulseDots,
} from 'premium-react-loaders';

function App() {
  return (
    <div>
      {/* Skeleton Loaders */}
      <Skeleton width={200} height={20} />
      <SkeletonCard hasAvatar lines={3} />

      {/* Spinners with Size Presets (v1.2.0+) */}
      <SpinnerCircle size="lg" color="#3b82f6" />
      <SpinnerCircle size="md" reverse /> {/* Reverse animation */}

      {/* Progress Bars */}
      <ProgressBar value={75} showValue />
      <ProgressBar indeterminate reverse /> {/* Reverse sweep */}

      {/* Pulse Loaders */}
      <PulseDots size="sm" dotCount={3} />
    </div>
  );
}

Component Categories

Skeleton Loaders (9 components)

Placeholder components that mimic content layout while loading:

  • Skeleton - Base skeleton component with variants
  • SkeletonText - Multi-line text placeholder
  • SkeletonAvatar - Avatar placeholder (circle/square)
  • SkeletonImage - Image placeholder with aspect ratio
  • SkeletonCard - Card layout with avatar + text
  • SkeletonForm - Form skeleton with inputs and labels
  • SkeletonList - List of skeleton items
  • SkeletonTable - Table skeleton with rows/columns
  • SkeletonPage - Pre-built full page layouts (default, dashboard, article, profile)

Spinner Loaders (7 components)

Rotating and animated spinners:

  • SpinnerCircle - Basic rotating circle spinner
  • SpinnerRing - Border-only ring spinner
  • SpinnerDots - Multiple dots rotating around center
  • SpinnerBars - Vertical bars with wave animation
  • SpinnerGrid - Grid of fading squares
  • SpinnerPulse - Pulsing circle spinner
  • SpinnerWave - Wave pattern spinner

Progress Loaders (4 components)

Progress indicators (determinate/indeterminate):

  • ProgressBar - Linear horizontal progress bar
  • ProgressCircle - Circular progress indicator
  • ProgressRing - Ring progress with gradient option
  • ProgressSteps - Multi-step progress indicator

Pulse Loaders (4 components)

Bouncing, pulsing, wave animations:

  • PulseDots - Bouncing dots in sequence
  • PulseWave - Wave pattern bars
  • PulseBars - Equalizer-style pulsing bars
  • TypingIndicator - Typing animation indicator

Overlay Components (1 component)

Wrapper component for displaying loaders over content:

  • LoaderOverlay - Displays any loader over content with backdrop (full-screen or container-relative)

Button Components (1 component) ✨ New in v2.2.0

Specialized loaders for button loading states:

  • ButtonSpinner - Compact spinner optimized for buttons with multiple variants (circle, dots, bars) and positioning options

Status Components (2 components) ✨ New in v2.2.0

Animated indicators for success and error states:

  • SuccessCheckmark - Animated checkmark with optional circle background
  • ErrorIndicator - Animated X mark with optional shake effect and circle background

Transition Components (1 component) ✨ New in v2.3.0

Smooth transitions between loading and loaded states:

  • LoaderTransition - Animated transitions between loading and content states with multiple animation types (fade, slide, scale)

Shimmer Components (3 components) ✨ New in v3.0.0

Shimmer effect placeholders with directional animations:

  • ShimmerBox - Shimmer container with customizable direction (left-to-right, right-to-left, top-to-bottom, bottom-to-top)
  • ShimmerText - Multi-line text shimmer placeholder
  • ShimmerButton - Button placeholder with shimmer effect

Orbit Components (3 components) ✨ New in v3.0.0

Orbital and atomic animations:

  • OrbitDots - Dots orbiting around a central point
  • OrbitRings - Concentric rotating rings
  • AtomLoader - Electron-like orbital animation with nucleus

Bounce Components (2 components) ✨ New in v3.0.0

Physics-based bouncing loaders:

  • BouncingDots - Dots with physics-based bounce animation
  • BouncingBalls - 3D bouncing balls with shadow and squash effects

Infinity Components (2 components) ✨ New in v3.0.0

Continuous loop animations:

  • InfinityLoader - Figure-8 infinity symbol animation with optional traveling dot
  • MobiusLoader - Segmented ribbon loop with twist effect

Text Components (1 component) ✨ New in v3.0.0

Animated loading text:

  • LoadingText - Animated loading text with multiple animation styles (dots, fade, bounce, wave)

3D Components (5 components) ✨ New in v3.1.0

Immersive 3D loaders with perspective transforms:

  • CubeSpinner - Rotating 3D cube with customizable faces and rotation axes (x, y, z, diagonal)
  • FlipCard - 3D card flip animation with horizontal/vertical modes
  • PlaneRotate - Multiple rotating planes in 3D space with synchronized/staggered modes
  • Helix - DNA-like spiral animation with particles and optional connecting lines
  • PerspectiveRing - 3D ring with tilt angle, shadow effects, and depth perception

Smart Components (3 components) ✨ New in v3.1.0

Intelligent, context-aware loading placeholders:

  • SmartSkeleton - Auto-detecting skeleton that analyzes content type (text, image, card, list, table, form)
  • FormFieldLoader - Loading states for form inputs (text, select, checkbox, radio, textarea, file)
  • DataTableSkeleton - Advanced table skeleton with headers, sorting, filtering, pagination, and selection

Accessibility Components (1 component) ✨ New in v3.1.0

Screen reader support and ARIA announcements:

  • LiveRegion - ARIA live region for screen reader announcements with configurable politeness levels

Hooks

Loading State Management

  • useLoader - Basic loading state with delay, minDuration, and autoHide (v2.1.0+)
  • useEnhancedLoader - Advanced loading with retry logic, success/error states, and history (v2.3.0+)
  • useLoadingOrchestrator - Manage multiple loading tasks with dependencies ✨ New in v3.1.0
  • useLoadingAnalytics - Track loading performance metrics and user experience ✨ New in v3.1.0
  • useSmartLoader - Intelligent loader with connection detection and progress estimation ✨ New in v3.1.0

Theming

  • useTheme - Access global theme configuration (v2.1.0+)

Usage Examples

Skeleton Components

import {
  Skeleton,
  SkeletonText,
  SkeletonAvatar,
  SkeletonCard,
} from 'premium-react-loaders';

// Basic skeleton
<Skeleton width={200} height={20} />

// Multi-line text
<SkeletonText lines={3} width="100%" />

// Avatar
<SkeletonAvatar size={48} shape="circle" />

// Card with avatar and text
<SkeletonCard hasAvatar lines={3} />

// Custom colors
<Skeleton
  width={200}
  height={20}
  baseColor="#e0e0e0"
  highlightColor="#f5f5f5"
/>

Spinner Components

import {
  SpinnerCircle,
  SpinnerRing,
  SpinnerDots,
} from 'premium-react-loaders';

// Basic spinner
<SpinnerCircle size={40} color="#3b82f6" />

// Ring spinner
<SpinnerRing size={32} thickness={4} />

// Dots spinner
<SpinnerDots size={40} dotCount={8} />

// Speed control
<SpinnerCircle size={40} speed="fast" />

Progress Components

import {
  ProgressBar,
  ProgressCircle,
  ProgressRing,
} from 'premium-react-loaders';

// Determinate progress
<ProgressBar value={75} showValue />

// Indeterminate progress
<ProgressBar indeterminate />

// Circular progress
<ProgressCircle value={60} showValue size={80} />

// Ring with gradient
<ProgressRing
  value={80}
  gradient
  color="#3b82f6"
  secondaryColor="#8b5cf6"
/>

Pulse Components

import { PulseDots, PulseWave, PulseBars } from 'premium-react-loaders';

// Bouncing dots
<PulseDots dotCount={3} color="#3b82f6" />

// Wave pattern
<PulseWave barCount={5} />

// Equalizer bars
<PulseBars barCount={4} speed="fast" />

New in v1.0.1

import { LoaderOverlay, SkeletonPage, SpinnerCircle } from 'premium-react-loaders';

// Page skeleton for full page loading
<SkeletonPage variant="dashboard" />
<SkeletonPage variant="article" />
<SkeletonPage variant="profile" />

// Loader overlay over content
<LoaderOverlay
  loading={isLoading}
  loader={<SpinnerCircle size={50} />}
  blur
>
  <YourContent />
</LoaderOverlay>

// Full-screen overlay with custom backdrop
<LoaderOverlay
  loading={isLoading}
  loader={<SpinnerCircle />}
  position="fixed"
  backdropOpacity={0.8}
  backdropColor="#000000"
>
  <YourApp />
</LoaderOverlay>

New in v1.2.0

Size Presets - Use semantic size names instead of pixel values:

import { SpinnerCircle, ProgressBar, PulseDots } from 'premium-react-loaders';

// Size presets: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
<SpinnerCircle size="xs" />  {/* 16px */}
<SpinnerCircle size="sm" />  {/* 24px */}
<SpinnerCircle size="md" />  {/* 40px - default */}
<SpinnerCircle size="lg" />  {/* 56px */}
<SpinnerCircle size="xl" />  {/* 72px */}

// Still works with numbers and CSS strings
<SpinnerCircle size={50} />
<SpinnerCircle size="3rem" />

Reduced Motion Support - Automatically respects user accessibility preferences:

// Respects prefers-reduced-motion by default
<SpinnerCircle size="md" />

// Disable reduced motion support if needed
<SpinnerCircle size="md" respectMotionPreference={false} />

Animation Direction Control - Reverse animations for creative effects:

import { SpinnerCircle, ProgressBar, PulseDots } from 'premium-react-loaders';

// Reverse spinner rotation (counter-clockwise)
<SpinnerCircle size="lg" reverse />

// Reverse progress sweep direction
<ProgressBar indeterminate reverse />

// Reverse pulse/dot animation sequence
<PulseDots size="md" reverse />

New in v2.3.0

LoaderTransition - Smooth transitions between loading and loaded states:

import { LoaderTransition, Skeleton } from 'premium-react-loaders';

// Eliminate jarring content switches
<LoaderTransition
  loading={isLoading}
  loadingContent={<Skeleton width={300} height={100} />}
  transitionType="fade"
  duration={300}
  delay={200}
  minDuration={600}
>
  <YourActualContent />
</LoaderTransition>

// Different transition types
<LoaderTransition loading={isLoading} loadingContent={<Spinner />} transitionType="slide-up">
  <Content />
</LoaderTransition>

<LoaderTransition loading={isLoading} loadingContent={<Skeleton />} transitionType="scale" timing="spring">
  <Content />
</LoaderTransition>

useEnhancedLoader - Supercharged loading state management:

import { useEnhancedLoader } from 'premium-react-loaders';

function MyComponent() {
  const {
    status,              // 'idle' | 'loading' | 'success' | 'error'
    error,               // Error object if failed
    retryAttempt,        // Current retry attempt number
    history,             // Loading history with timestamps
    startLoading,
    stopLoading,
    setError,
    retry,
    reset,
  } = useEnhancedLoader({
    delay: 200,
    minDuration: 600,
    retry: {
      maxRetries: 3,
      initialDelay: 1000,
      backoffMultiplier: 2,
    },
    debounce: 300,       // Debounce loading starts
    onSuccess: () => console.log('Success!'),
    onError: (err) => console.error(err),
  });

  const fetchData = async () => {
    startLoading();
    try {
      const data = await api.fetch();
      stopLoading();
    } catch (err) {
      setError(err);
    }
  };

  return (
    <div>
      {status === 'loading' && <SpinnerCircle visible={isVisible} />}
      {status === 'success' && <SuccessCheckmark visible />}
      {status === 'error' && (
        <>
          <ErrorIndicator visible />
          <button onClick={retry}>Retry ({retryAttempt}/3)</button>
        </>
      )}
    </div>
  );
}

New in v2.2.0

Button Loaders - Specialized spinners for button states:

import { ButtonSpinner } from 'premium-react-loaders';

// Inside a button
<button style={{ padding: '10px 20px', backgroundColor: '#3b82f6', color: 'white' }}>
  <ButtonSpinner variant="circle" size={16} color="white">
    Submit Form
  </ButtonSpinner>
</button>

// Different variants
<ButtonSpinner variant="dots" position="right">Next</ButtonSpinner>
<ButtonSpinner variant="bars" showContent={false}>Loading</ButtonSpinner>

Status Indicators - Show success and error states with smooth animations:

import { SuccessCheckmark, ErrorIndicator } from 'premium-react-loaders';

// Success state
<SuccessCheckmark
  visible={isSuccess}
  showCircle
  fillCircle
  size={64}
  color="#10b981"
/>

// Error state with shake
<ErrorIndicator
  visible={hasError}
  showCircle
  shake
  size={64}
  color="#ef4444"
/>

New in v2.1.0

Global Theming - Customize all loaders from one place:

import { ThemeProvider } from 'premium-react-loaders';

function App() {
  return (
    <ThemeProvider
      theme={{
        primaryColor: '#8b5cf6',
        secondaryColor: '#ec4899',
        skeletonBase: '#e2e8f0',
        skeletonHighlight: '#f1f5f9',
        defaultSize: 'lg',
        defaultSpeed: 'fast',
        defaultDelay: 200,
        defaultMinDuration: 600,
        respectMotionPreference: true,
      }}
    >
      {/* All loaders inherit these settings */}
      <SpinnerCircle /> {/* Uses theme colors and size */}
      <Skeleton /> {/* Uses theme skeleton colors */}
    </ThemeProvider>
  );
}

Smart Loading State Management - Better UX with the useLoader hook:

import { useLoader } from 'premium-react-loaders';
import { SpinnerCircle } from 'premium-react-loaders';

function MyComponent() {
  const { loading, startLoading, stopLoading, isVisible } = useLoader({
    delay: 200,        // Don't show loader for quick operations (<200ms)
    minDuration: 600,  // Show loader for at least 600ms to avoid flashing
    autoHide: 5000,    // Auto-hide after 5 seconds (optional)
  });

  const fetchData = async () => {
    startLoading();
    try {
      await api.fetchData();
    } finally {
      stopLoading();
    }
  };

  return (
    <div>
      <button onClick={fetchData}>Load Data</button>
      <SpinnerCircle visible={isVisible} />
    </div>
  );
}

Enhanced CSS Variables - More control with comprehensive theming:

:root {
  /* Colors */
  --loader-primary: #3b82f6;
  --loader-secondary: #8b5cf6;
  --skeleton-base: #e5e7eb;
  --skeleton-highlight: #f5f5f5;

  /* Sizes */
  --loader-size-xs: 16px;
  --loader-size-sm: 24px;
  --loader-size-md: 40px;
  --loader-size-lg: 56px;
  --loader-size-xl: 72px;

  /* Animation */
  --loader-transition-fast: 150ms;
  --loader-transition-normal: 300ms;
  --loader-transition-slow: 500ms;
}

/* Dark mode support */
@media (prefers-color-scheme: dark) {
  :root {
    --skeleton-base: #2d3748;
    --skeleton-highlight: #4a5568;
  }
}

Improved TypingIndicator - Smoother animations with dynamic timing that scales with speed settings.

Customization

All components support multiple customization methods:

1. className Prop

Pass custom CSS classes:

<SpinnerCircle size={40} className="my-spinner" />

2. style Prop

Use inline CSS styles:

<ProgressBar value={75} style={{ opacity: 0.8, margin: '20px 0' }} />

3. Color Props

Direct color control:

<SpinnerCircle color="#8b5cf6" secondaryColor="#e0e0e0" />

4. CSS Variables (Enhanced in v2.1.0)

Override theme variables globally for comprehensive customization:

:root {
  /* Primary colors */
  --loader-primary: #3b82f6;
  --loader-secondary: #8b5cf6;

  /* Skeleton colors */
  --skeleton-base: #e5e7eb;
  --skeleton-highlight: #f5f5f5;

  /* Size presets */
  --loader-size-xs: 16px;
  --loader-size-sm: 24px;
  --loader-size-md: 40px;
  --loader-size-lg: 56px;
  --loader-size-xl: 72px;

  /* Spacing and layout */
  --loader-gap: 0.5rem;
  --loader-radius-sm: 0.25rem;
  --loader-radius-md: 0.5rem;
  --loader-radius-lg: 1rem;
  --loader-radius-full: 9999px;

  /* Animation speeds */
  --loader-transition-fast: 150ms;
  --loader-transition-normal: 300ms;
  --loader-transition-slow: 500ms;

  /* Overlay */
  --loader-overlay-backdrop: rgba(0, 0, 0, 0.5);
}

/* Dark mode support */
@media (prefers-color-scheme: dark) {
  :root {
    --skeleton-base: #2d3748;
    --skeleton-highlight: #4a5568;
  }
}

5. ThemeProvider (v2.1.0+)

Use the ThemeProvider component for runtime theming:

import { ThemeProvider, useTheme } from 'premium-react-loaders';

function App() {
  return (
    <ThemeProvider
      theme={{
        primaryColor: '#8b5cf6',
        secondaryColor: '#ec4899',
        defaultSize: 'lg',
      }}
    >
      <YourComponents />
    </ThemeProvider>
  );
}

// Access theme in child components
function ChildComponent() {
  const { theme } = useTheme();
  return <SpinnerCircle />; // Automatically uses theme settings
}

TypeScript

Full TypeScript support with exported types:

import type {
  SkeletonProps,
  SpinnerCircleProps,
  ProgressBarProps,
  PulseDotsProps,
  LoaderTheme,
  UseLoaderOptions,
  UseLoaderReturn,
} from 'premium-react-loaders';

const MyComponent: React.FC = () => {
  const skeletonProps: SkeletonProps = {
    width: 200,
    height: 20,
    animate: true,
  };

  return <Skeleton {...skeletonProps} />;
};

// Theme typing (v2.1.0+)
const customTheme: LoaderTheme = {
  primaryColor: '#8b5cf6',
  secondaryColor: '#ec4899',
  defaultSize: 'lg',
  defaultSpeed: 'fast',
};

// useLoader hook typing (v2.1.0+)
const loaderOptions: UseLoaderOptions = {
  delay: 200,
  minDuration: 600,
  autoHide: 5000,
};

Common Props

All loader components share these common props:

Prop Type Default Description
size number | string varies Size of the loader
color string #3b82f6 Primary color
className string - Custom CSS class
style CSSProperties - Inline styles
visible boolean true Show/hide loader
speed 'slow' | 'normal' | 'fast' | number 'normal' Animation speed
testId string - Test ID for testing
ariaLabel string - Accessibility label

Component-Specific Props

Skeleton Props

Prop Type Default Description
width number | string 100% Width of skeleton
height number | string 1rem Height of skeleton
variant 'text' | 'circular' | 'rectangular' | 'rounded' 'text' Shape variant
animate boolean true Enable shimmer animation
baseColor string #e0e0e0 Background color
highlightColor string #f5f5f5 Shimmer color

Progress Props

Prop Type Default Description
value number 0 Progress value (0-100)
indeterminate boolean false Indeterminate mode
showValue boolean false Show percentage text
thickness number | string varies Thickness of indicator

Performance

All components are optimized for performance:

  • CSS Animations - No JavaScript animations, pure CSS
  • Hardware Acceleration - Uses transform and opacity for 60fps
  • Tree-shakeable - Only bundle components you import
  • Minimal Bundle Size - Lightweight with no dependencies

Browser Support

  • Chrome (latest)
  • Firefox (latest)
  • Safari (latest)
  • Edge (latest)

Storybook

Explore all components interactively in Storybook:

npm run storybook

Contributing

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

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

License

MIT © Ishan Karunaratne

Migrating from v1.x to v2.0

v2.0.0 removes the Tailwind CSS dependency for a simpler, lighter library. Here's what changed:

Breaking Changes

  1. No Tailwind Required - The library now uses custom CSS instead of Tailwind
  2. No Tailwind Configuration Needed - Remove the library path from your tailwind.config.js
  3. Slightly Different Styling - Components use the same class names but with custom CSS utilities

Migration Steps

  1. Update the package:

    npm install premium-react-loaders@latest
  2. Remove Tailwind configuration (if you're not using Tailwind for other parts of your app):

    // Remove this from tailwind.config.js
    './node_modules/premium-react-loaders/dist/**/*.{js,ts,jsx,tsx}'
  3. That's it! Your components will continue to work with the same API. The styling is now self-contained.

What Stayed the Same

  • ✅ All component APIs are identical
  • ✅ All props work exactly the same
  • ✅ TypeScript types unchanged
  • ✅ Same import paths
  • ✅ Same customization options (className, style, color props)

Benefits of v2.0

  • 🎉 70% smaller CSS bundle (21KB → 6.27KB, 1.64KB gzipped)
  • 🎉 36% smaller total package (1.0MB → 640KB)
  • 🎉 Zero configuration - no Tailwind setup required
  • 🎉 Works in any React project - not just Tailwind projects
  • 🎉 Faster installation - fewer dependencies to download

Acknowledgments

Built with:


Made with ❤️ by Ishan Karunaratne

About

Premium React Loaders - A comprehensive collection of premium, production-ready loading components for React applications. Built with TypeScript and Tailwind CSS for maximum flexibility and customization.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Contributors 2

  •  
  •