React Easy Loaders

A fully customizable React loader toolkit with theming, overlays, registry, and createLoader API.

🚀 Live Demo & Documentation

Explore 12 beautiful loading animations, interactive examples, and comprehensive documentation on our GitHub Pages site.

Quick Stats

• 📦 Bundle Size: < 8KB gzipped
• 🚀 Zero Dependencies: No external runtime dependencies
• ⚛️ React Support: Works with React 17 and 18
• 🔧 TypeScript: 100% TypeScript with full type definitions
• 🎯 Framework Agnostic: Next.js, Vite, CRA compatible
• 🎨 12 Built-in Loaders: Ready-to-use components

Table of Contents

• Quick Stats
• Features
• Installation
• Quick Start
• Built-in Loaders
• API Reference
• Customization
• Framework Compatibility
• TypeScript Support
• Links & Resources
• Development
• Contributing
• License

Features

• 🎨 12 Built-in Loaders: Spinner, Ring, DualRing, Dots, Bars, Pulse, Bounce, Ripple, Roller, Grid, Wave, Progress
• 🎯 Dual API Design: Direct component usage and dynamic loader system
• 🎪 Theme System: Global theming with LoaderProvider
• 🔄 Overlay System: Full-screen loading states with context integration
• 🛠️ Custom Loaders: Create your own with createLoader function
• 🔧 Registry System: Register and manage custom loaders dynamically
• 📱 SSR Compatible: Works with Next.js and other SSR frameworks
• 🌳 Tree Shakable: Import only what you need
• ⚡ Lightweight: Minimal bundle size with zero dependencies
• 🎨 Fully Customizable: Easy CSS override system
• 🔧 TypeScript First: Complete type safety and IntelliSense support

Installation

npm install react-easy-loaders

Quick Start

1. Basic Usage

Import and use any loader directly:

import { Spinner, Ring, Progress } from "react-easy-loaders";

function App() {
  return (
    <div>
      <Spinner color="#4CAF50" size={40} />
      <Ring color="#2196F3" size={50} />
      <Progress color="#FF9800" size={40} progress={75} />
    </div>
  );
}

2. With Theme Provider

Use the provider for consistent theming across all loaders:

import { LoaderProvider, useLoader, Spinner } from "react-easy-loaders";

function MyComponent() {
  const { showLoader, hideLoader } = useLoader();

  const handleClick = () => {
    showLoader(<Spinner />, "Loading...");
    setTimeout(hideLoader, 3000);
  };

  return <button onClick={handleClick}>Show Loader</button>;
}

function App() {
  return (
    <LoaderProvider value={{ color: "#4CAF50", size: 40, speed: 1.2 }}>
      <MyComponent />
    </LoaderProvider>
  );
}

3. Dynamic Loader

Use the dynamic loader system to load any loader by name:

import { Loader } from "react-easy-loaders";

function App() {
  return (
    <div>
      <Loader type="spinner" color="#4CAF50" size={50} />
      <Loader type="ring" color="#2196F3" size={50} />
      <Loader type="dots" color="#FF9800" size={50} />
    </div>
  );
}

Built-in Loaders

Our library includes 12 beautiful, customizable loader components:

| Component | Description | Animation Type | | -------------- | ---------------------------- | ----------------- | | <Spinner /> | Classic spinning circle | Rotation | | <Ring /> | Animated ring with dash | Circular stroke | | <DualRing /> | Double concentric rings | Counter rotation | | <Dots /> | Three bouncing dots | Vertical bounce | | <Bars /> | Scaling rectangular bars | Height scaling | | <Pulse /> | Pulsing circle effect | Scale transform | | <Bounce /> | Two bouncing circles | Alternating scale | | <Ripple /> | Water ripple effect | Expanding rings | | <Roller /> | Rolling circles in sequence | Sequential motion | | <Grid /> | 3x3 grid of animated squares | Fade in/out | | <Wave /> | Horizontal wave animation | Sequential bars | | <Progress /> | Linear progress indicator | Width transition |

Basic Props

All loaders accept these common properties:

interface LoaderBaseProps {
  color?: string; // Primary color (default: "#4b6bfb")
  size?: number; // Size in pixels (default: 40)
  speed?: number; // Animation speed multiplier (default: 1)
  className?: string; // CSS class name
  style?: CSSProperties; // Inline styles
  ssrFallback?: ReactNode; // SSR fallback content
}

API Reference

LoaderProvider

The main provider component for global theming and overlay management:

<LoaderProvider value={{ color: "#4CAF50", size: 40 }}>
  {/* Your app */}
</LoaderProvider>

Props

| Prop | Type | Default | Description | | ---------- | ------------- | ------- | -------------------------- | | value | LoaderTheme | {} | Global theme configuration | | children | ReactNode | - | Your app components |

useLoader Hook

Hook for programmatic overlay control:

const { showLoader, hideLoader, setTheme } = useLoader();

// Show overlay loader
showLoader(<Spinner />, "Loading...");

// Hide overlay loader
hideLoader();

// Update theme
setTheme({ color: "#FF0000", size: 50 });

LoaderOverlay Component

Direct overlay component usage:

<LoaderOverlay
  open={isLoading}
  loader={<Spinner color="#fff" />}
  message="Loading your content..."
  backdropColor="rgba(0,0,0,0.7)"
  zIndex={9999}
  lockScroll={true}
/>

createLoader Function

Create custom loaders:

import { createLoader } from "react-easy-loaders";

const CustomLoader = createLoader(
  ({ color, size, speed, className, style }) => (
    <div className={className} style={{ ...style, color, fontSize: size }}>
      ⭐ {/* Your custom animation */}
    </div>
  )
);

// Use it
<CustomLoader color="gold" size={30} />;

Dynamic Loader

import { Loader } from "react-easy-loaders";

<Loader
  type="spinner"
  color="#4CAF50"
  size={40}
  // Any other props specific to the loader type
/>;

Customization

Override CSS classes to customize appearance:

/* Global loader styles */
.loader-base {
  /* Your custom styles */
}

/* Specific loader customization */
.custom-spinner {
  border-width: 3px;
  border-color: #your-color;
}

/* Overlay customization */
.loader-overlay {
  backdrop-filter: blur(4px);
}

Framework Compatibility

Next.js

// pages/_app.tsx
import { LoaderProvider } from "react-easy-loaders";

export default function MyApp({ Component, pageProps }) {
  return (
    <LoaderProvider value={{ color: "#0070f3" }}>
      <Component {...pageProps} />
    </LoaderProvider>
  );
}

Vite

// main.tsx
import { LoaderProvider } from "react-easy-loaders";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <LoaderProvider>
    <App />
  </LoaderProvider>
);

Works seamlessly with Create React App, Remix, and other React frameworks.

TypeScript Support

Full TypeScript support with complete type definitions:

import type {
  LoaderBaseProps,
  LoaderComponent,
  LoaderTheme,
  OverlayProps,
} from "react-easy-loaders";

const theme: LoaderTheme = {
  color: "#4CAF50",
  size: 40,
  speed: 1.2,
};

const customLoader: LoaderComponent = ({ color, size }) => (
  <div style={{ color, fontSize: size }}>Loading...</div>
);

Links & Resources

• 🚀 Live Demo & Examples - Interactive demo with all loaders
• 📦 npm Package - Install via npm
• 🐙 GitHub Repository - Source code and issues
• 🔧 TypeScript Definitions - View type definitions
• 📊 Bundle Analysis - Package size analysis

Development

Setup

# Clone the repository
git clone https://github.com/deveshlashkari/react-easy-loaders.git
cd react-easy-loaders

# Install dependencies
npm install

# Build the package
npm run build

# Run demo locally
npm run demo:dev

Scripts

| Script | Description | | -------------------- | -------------------------------- | | npm run build | Build the package for production | | npm run dev | Start demo development server | | npm run demo:build | Build demo for production | | npm run typecheck | Type check the codebase | | npm run clean | Clean build artifacts | | npm run release | Build and publish to npm |

Contributing

Contributions are welcome! Here's how you can help:

1. 🍴 Fork the repository
2. 🔧 Create a feature branch: git checkout -b feature/amazing-loader
3. ✅ Make your changes and test them
4. 🧪 Test in the demo: npm run demo:dev
5. 📝 Commit your changes: git commit -m 'Add amazing loader'
6. 🚀 Push to the branch: git push origin feature/amazing-loader
7. 🎉 Open a Pull Request

Guidelines

• Follow the existing code style and patterns
• Add new loaders to both the library and demo
• Update documentation as needed
• Ensure TypeScript types are properly defined
• Test your changes in multiple frameworks if possible

License

MIT © Devesh Lashkari

This project is licensed under the MIT License - see the LICENSE file for details.

function MyComponent() { const { showLoader, hideLoader } = useLoader();

const handleClick = () => { showLoader(, "Loading..."); setTimeout(hideLoader, 3000); };

return Show Loader; }

function App() { return ( <LoaderProvider value={{ color: "#4CAF50", size: 40 }}> ); }

## 📚 Components

### Built-in Loaders

| Component      | Description             |
| -------------- | ----------------------- |
| `<Spinner />`  | Classic spinning loader |
| `<Ring />`     | Animated ring with dash |
| `<DualRing />` | Double ring animation   |
| `<Dots />`     | Bouncing dots           |
| `<Bars />`     | Scaling bars            |
| `<Pulse />`    | Pulsing circle          |
| `<Bounce />`   | Bouncing circles        |
| `<Ripple />`   | Water ripple effect     |
| `<Roller />`   | Rolling circles         |
| `<Grid />`     | Grid of squares         |
| `<Wave />`     | Wave animation          |
| `<Progress />` | Progress bar            |

### Core Components

- `<LoaderProvider />` - Theme provider
- `<LoaderOverlay />` - Full-screen overlay
- `<Loader />` - Dynamic loader by type
- `createLoader()` - Create custom loaders

### Hooks

- `useLoader()` - Control overlay loaders
- `useLoaderTheme()` - Access current theme

## 🎨 Theming

```tsx
import { LoaderProvider } from "react-easy-loaders";

const theme = {
  color: "#4CAF50",
  size: 40,
  speed: 1.2,
  className: "my-loader",
  style: { margin: "10px" },
};

function App() {
  return (
    <LoaderProvider value={theme}>
      {/* All loaders inherit theme */}
    </LoaderProvider>
  );
}

🛠️ Custom Loaders

import { createLoader } from 'react-easy-loaders'

const HeartLoader = createLoader(
  ({ color, size, speed, className, style }) => (
    <div
      className={className}
      style={{
        fontSize: size,
        color,
        animation: `heartbeat ${1 / speed}s ease-in-out infinite`,
        ...style,
      }}
    >
      ❤️
      <style>{`
        @keyframes heartbeat {
          0%, 100% { transform: scale(1); }
          50% { transform: scale(1.2); }
        }
      `}</style>
    </div>
  )
)

// Use it
<HeartLoader color="red" size={30} speed={2} />

📡 Dynamic Loaders

import { Loader } from 'react-easy-loaders'

// Load any built-in loader by name
<Loader type="spinner" color="#4CAF50" size={40} />
<Loader type="ring" color="#2196F3" size={50} />
<Loader type="progress" progress={75} />

🔄 Overlay System

import { LoaderOverlay, useLoader } from "react-easy-loaders";

// Method 1: Direct component
<LoaderOverlay
  open={isLoading}
  loader={<Spinner color="#fff" />}
  message="Loading your content..."
  backdropColor="rgba(0,0,0,0.7)"
/>;

// Method 2: Using context
function MyComponent() {
  const { showLoader, hideLoader } = useLoader();

  const handleLoad = async () => {
    showLoader(<Ring color="#fff" />, "Please wait...");
    await fetchData();
    hideLoader();
  };
}

🧪 Demo

Run the interactive demo to see all loaders in action:

# From the project root
npm run demo:install
npm run demo:dev

Or visit the live demo (coming soon!)

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT © Devesh Lashkari

🌟 Show Your Support

If this project helped you, please give it a ⭐️!