# Premium React Loaders A comprehensive collection of **70+ 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 70+ components in action with interactive examples and customization options. ## Features - **70+ Premium Components** across 21 categories (Skeleton, Spinner, Progress, Pulse, Overlay, Button, Status, Transition, Shimmer, Orbit, Bounce, Infinity, Text, 3D, Smart, Morph, Gradient, Particle, Neon, Chart, Accessibility) - **6 Powerful Hooks** - useLoader, useEnhancedLoader, useLoadingOrchestrator, useLoadingAnalytics, useSmartLoader, useTheme ✨ *New in v3.1.0* - **Chart Skeletons** - Bar, line, and donut chart placeholders for dashboards ✨ *New in v4.2.0* - **Neon Loaders** - Glowing neon-style pulse, spinner, text, progress, and dots for dark UIs ✨ *New in v4.1.0* - **Extended Status Set** - WarningIndicator and InfoIndicator complete the status family ✨ *New in v4.1.0* - **Particle Enhancements** - ParticleTrail and ParticleField ambient effects ✨ *New in v4.1.0* - **Morph Loaders** - Fluid organic blob, liquid fill, and wave circle animations ✨ *New in v4.0.0* - **Gradient Loaders** - Animated conic gradient spinners and flowing gradient bars ✨ *New in v4.0.0* - **Particle Loaders** - CSS particle burst and orbital animations ✨ *New in v4.0.0* - **onComplete Callback** - Fire callbacks when progress reaches 100% ✨ *New in v4.0.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 ``` ### 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 (4 components) ✨ *New in v2.2.0 / Extended in v4.1.0* Animated indicators for operation outcomes: - **SuccessCheckmark** - Animated checkmark with optional circle background - **ErrorIndicator** - Animated X mark with optional shake effect and circle background - **WarningIndicator** - Animated warning triangle with `!` mark; optional `shake` effect ✨ *New in v4.1.0* - **InfoIndicator** - Animated info badge with `i` mark; optional `pulse` glow ✨ *New in v4.1.0* ### 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 ### Morph Components (3 components) ✨ *New in v4.0.0* Fluid, organic animation components based on CSS morphing: - **MorphBlob** - Organic blob shape that continuously morphs between randomized border-radius states - **LiquidFill** - Circular container that fills with an animated liquid level (determinate and indeterminate modes) - **WaveCircle** - Concentric circular ripples emanating outward from the center like a sonar pulse ### Gradient Components (5 components) ✨ *New in v4.0.0 / Extended in v4.2.0* Visually striking spinners and progress indicators using animated CSS gradients: - **GradientSpinner** - Circular spinner filled with a sweeping conic gradient that rotates continuously - **GradientRing** - Ring with a moving gradient that travels around its circumference - **GradientBar** - Horizontal progress bar with a flowing gradient shimmer animation - **GradientText** - Loading text filled with a flowing animated gradient via `background-clip: text` ✨ *New in v4.2.0* - **GradientDots** - Bouncing dots sharing an animated two-color gradient fill; configurable `dotCount`, `dotSize` ✨ *New in v4.2.0* ### Particle Components (4 components) ✨ *New in v4.0.0 / Extended in v4.1.0* Particle-based loaders using CSS-positioned elements for dynamic visual effects: - **ParticleBurst** - Particles that periodically burst outward from a central point and fade as they travel - **ParticleOrbit** - Multiple particles floating in circular orbits around a central dot with staggered delays - **ParticleTrail** - Particles trailing along a circular orbit with opacity and size fade; configurable `count` (3–10) ✨ *New in v4.1.0* - **ParticleField** - Ambient field of floating, drifting particles rising through a bounded area; configurable `width`, `height`, `count` (5–30) ✨ *New in v4.1.0* ### Neon Components (5 components) ✨ *New in v4.1.0 / Extended in v4.2.0* Glowing neon-style loaders using CSS box-shadow and text-shadow for dark UIs and gaming themes: - **NeonPulse** - Pulsing glowing ring with configurable `glowIntensity` (`low` / `medium` / `high`) - **NeonSpinner** - Spinning arc with a neon glow trail; customizable `thickness` and `color` - **NeonText** - Loading text label that pulses with a neon glow; configurable `text`, `color`, `fontSize` - **NeonProgress** - Progress bar with a glowing neon fill; determinate/indeterminate with an `onComplete` callback ✨ *New in v4.2.0* - **NeonDots** - Bouncing dots with a glowing neon box-shadow; configurable `dotCount`, `dotSize`, `color` ✨ *New in v4.2.0* ### Chart Components (3 components) ✨ *New in v4.2.0* Skeleton placeholders shaped like common chart types, for dashboards that load data asynchronously: - **BarChartSkeleton** - Bar chart placeholder with a deterministic wave-height pattern; configurable `bars` (3–12), optional `showAxis` baseline - **LineChartSkeleton** - Line/trend chart placeholder with a flowing dashed path; configurable `points` (3–10), optional `showGrid` - **DonutChartSkeleton** - Donut/pie chart placeholder built from alternating conic-gradient slices; configurable `segments` (2–6), optional `showLabel` ## 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 ```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' && ( <> )}
); } ``` ### New in v2.2.0 **Button Loaders** - Specialized spinners for button states: ```tsx import { ButtonSpinner } from 'premium-react-loaders'; // Inside a button // 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 (
); } ``` **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**