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.


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

``bash
npm install premium-react-loaders
`

$3

This library only requires React:

`bash
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):

`typescript
import 'premium-react-loaders/styles';
`

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

$3

Wrap your app with ThemeProvider to customize all loaders globally:

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

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


);
}
`

Quick Start

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

function App() {
return (



);
}
`

Component Categories

$3

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)

$3

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

$3

Progress indicators (determinate/indeterminate):

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

$3

Bouncing, pulsing, wave animations:

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

$3

Wrapper component for displaying loaders over content:

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

$3

Specialized loaders for button loading states:

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

$3

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

$3

Smooth transitions between loading and loaded states:

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

$3

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

$3

Orbital and atomic animations:

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

$3

Physics-based bouncing loaders:

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

$3

Continuous loop animations:

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

$3

Animated loading text:

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

$3

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

$3

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

$3

Screen reader support and ARIA announcements:

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

Hooks

$3

- 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

$3

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

Usage Examples

$3

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

// Basic skeleton


// Multi-line text


// Avatar


// Card with avatar and text


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

$3

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

// Basic spinner


// Ring spinner


// Dots spinner


// Speed control

`

$3

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

// Determinate progress


// Indeterminate progress


// Circular progress


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

$3

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

// Bouncing dots


// Wave pattern


// Equalizer bars

`

$3

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

// Page skeleton for full page loading




// Loader overlay over content
loading={isLoading}
loader={}
blur
>



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


`

$3

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

`

$3

LoaderTransition - Smooth transitions between loading and loaded states:

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

// Eliminate jarring content switches
loading={isLoading}
loadingContent={}
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 (



);
}
`

$3

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
visible={isSuccess}
showCircle
fillCircle
size={64}
color="#10b981"
/>

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

$3

Global Theming - Customize all loaders from one place:

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

function App() {
return (
theme={{
primaryColor: '#8b5cf6',
secondaryColor: '#ec4899',
skeletonBase: '#e2e8f0',
skeletonHighlight: '#f1f5f9',
defaultSize: 'lg',
defaultSpeed: 'fast',
defaultDelay: 200,
defaultMinDuration: 600,
respectMotionPreference: true,
}}
>
{/ 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 (



);
}
`

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:

$3

Pass custom CSS classes:

`tsx

`

$3

Use inline CSS styles:

`tsx

`

$3

Direct color control:

`tsx

`

$3

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;
}
}
`

$3

Use the ThemeProvider component for runtime theming:

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

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


);
}

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

$3

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

$3

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

$3

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

$3

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.

$3

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

$3

- 🎉 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
- TypeScript
- Vite
- Storybook

---

Made with ❤️ by Ishan Karunaratne