Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ishansasika/premium-react-loaders

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.
https://github.com/ishansasika/premium-react-loaders

loader loader-plugin loaders npm-package skeleton skeleton-loader skeleton-loading

Last synced: 26 days ago
JSON representation

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.

Awesome Lists containing this project

README 

          
# Premium React Loaders



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



[![npm version](https://img.shields.io/npm/v/premium-react-loaders.svg)](https://www.npmjs.com/package/premium-react-loaders)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)



## Demo



🚀 **[Interactive Demo](https://premium-react-loaders.ishansasika.dev/)** - Playground with live controls and component customization



📚 **[Storybook Documentation](https://docs.premium-react-loaders.ishansasika.dev/)** - Detailed component documentation and examples



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



## Features



- **40 Premium Components** across 13 categories (Skeleton, Spinner, Progress, Pulse, Overlay, Button, Status, Transition, Shimmer, Orbit, Bounce, Infinity, Text)

- **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



```bash

npm install premium-react-loaders

```



### Peer Dependencies



This library only requires React:



```bash

npm install react react-dom

```



> **Note:** v2.0.0+ no longer requires Tailwind CSS! See [Migration Guide](#migrating-from-v1x-to-v20) below.



## Setup



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



```typescript

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:



```tsx

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



function App() {

  return (

    

      

    

  );

}

```



## Quick Start



```tsx

import {

  Skeleton,

  SkeletonCard,

  SpinnerCircle,

  ProgressBar,

  PulseDots,

} from 'premium-react-loaders';



function App() {

  return (

    


      {/* Skeleton Loaders */}

      

      



      {/* Spinners with Size Presets (v1.2.0+) */}

      

       {/* Reverse animation */}



      {/* Progress Bars */}

      

       {/* Reverse sweep */}



      {/* Pulse Loaders */}

      

    


  );

}

```



## 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)



## Usage Examples



### Skeleton Components



```tsx

import {

  Skeleton,

  SkeletonText,

  SkeletonAvatar,

  SkeletonCard,

} from 'premium-react-loaders';



// Basic skeleton



// Multi-line text



// Avatar



// Card with avatar and text



// Custom colors



```



### Spinner Components



```tsx

import {

  SpinnerCircle,

  SpinnerRing,

  SpinnerDots,

} from 'premium-react-loaders';



// Basic spinner



// Ring spinner



// Dots spinner



// Speed control



```



### Progress Components



```tsx

import {

  ProgressBar,

  ProgressCircle,

  ProgressRing,

} from 'premium-react-loaders';



// Determinate progress



// Indeterminate progress



// Circular progress



// Ring with gradient



```



### Pulse Components



```tsx

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



// Bouncing dots



// Wave pattern



// Equalizer bars



```



### New in v1.0.1



```tsx

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



// Page skeleton for full page loading



// Loader overlay over content

}

  blur

>

  



// Full-screen overlay with custom backdrop

}

  position="fixed"

  backdropOpacity={0.8}

  backdropColor="#000000"

>

  



```



### New in v1.2.0



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



```tsx

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



// Size presets: 'xs' | 'sm' | 'md' | 'lg' | 'xl'

  {/* 16px */}

  {/* 24px */}

  {/* 40px - default */}

  {/* 56px */}

  {/* 72px */}



// Still works with numbers and CSS strings



```



**Reduced Motion Support** - Automatically respects user accessibility preferences:



```tsx

// Respects prefers-reduced-motion by default



// Disable reduced motion support if needed



```



**Animation Direction Control** - Reverse animations for creative effects:



```tsx

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



// Reverse spinner rotation (counter-clockwise)



// Reverse progress sweep direction



// Reverse pulse/dot animation sequence



```



### New in v2.3.0



**LoaderTransition** - Smooth transitions between loading and loaded states:



```tsx

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



// Eliminate jarring content switches

}

  transitionType="fade"

  duration={300}

  delay={200}

  minDuration={600}

>

  



// Different transition types

} transitionType="slide-up">

  



} transitionType="scale" timing="spring">

  



```



**useEnhancedLoader** - Supercharged loading state management:



```tsx

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 (

    


      {status === 'loading' && }

      {status === 'success' && }

      {status === 'error' && (

        <>

          

          Retry ({retryAttempt}/3)

        >

      )}

    


  );

}

```



### New in v2.2.0



**Button Loaders** - Specialized spinners for button states:



```tsx

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



// Inside a button



  

    Submit Form

  



// Different variants

Next

Loading

```



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



```tsx

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



// Success state



// Error state with shake



```



### New in v2.1.0



**Global Theming** - Customize all loaders from one place:



```tsx

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



function App() {

  return (

    

      {/* All loaders inherit these settings */}

       {/* Uses theme colors and size */}

       {/* Uses theme skeleton colors */}

    

  );

}

```



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



```tsx

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 (

    


      Load Data

      

    


  );

}

```



**Enhanced CSS Variables** - More control with comprehensive theming:



```css

: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:



```tsx



```



### 2. style Prop



Use inline CSS styles:



```tsx



```



### 3. Color Props



Direct color control:



```tsx



```



### 4. CSS Variables (Enhanced in v2.1.0)



Override theme variables globally for comprehensive customization:



```css

: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:



```tsx

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



function App() {

  return (

    

      

    

  );

}



// Access theme in child components

function ChildComponent() {

  const { theme } = useTheme();

  return ; // Automatically uses theme settings

}

```



## TypeScript



Full TypeScript support with exported types:



```typescript

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 ;

};



// 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:



```bash

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:**

   ```bash

   npm install premium-react-loaders@latest

   ```



2. **Remove Tailwind configuration** (if you're not using Tailwind for other parts of your app):

   ```javascript

   // 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:

- [React](https://react.dev/)

- [TypeScript](https://www.typescriptlang.org/)

- [Vite](https://vite.dev/)

- [Storybook](https://storybook.js.org/)



---



**Made with ❤️ by Ishan Karunaratne**