loader-overlay

A fully-featured React loader overlay component — 5 animation types, full theme control, progress tracking, outside-click dismissal, and zero dependencies.

🌐 Live Demo

👉 Try the interactive playground →

✨ Features

• 🎡 5 loader types — spinner, dots, pulse, ring, bar
• 🎨 5 variants — dark, light, blur, transparent, gradient
• 📊 Progress bar — animated shimmer progress tracking
• 🖱️ Outside click dismiss — close on backdrop click
• ⏱️ Auto-dismiss — timeout-based auto-hide
• ♿ Accessible — keyboard and screen reader friendly
• 📦 Zero dependencies — only peer dep is React 17+
• 🌳 Tree-shakeable — ESM and CJS builds
• 💙 TypeScript ready — full type definitions included

📦 Installation

# npm
npm install loader-overlay

# yarn
yarn add loader-overlay

# pnpm
pnpm add loader-overlay

# bun
bun add loader-overlay

Peer Dependencies

Make sure these are already in your project:

{
  "react": ">=17.0.0",
  "react-dom": ">=17.0.0"
}

💻 Local Installation

We provide a dedicated consumer-demo application directly in the repository to guarantee a seamless local installation testing environment out-of-the-box.

Using the Built-in Consumer Demo

git clone https://github.com/swapnilhpatil/loader-overlay-plugin.git
cd loader-overlay-plugin
npm install && npm run build

# Navigate to the standalone consumer-demo test application
cd consumer-demo
npm install          # Automatically links to file:../
npm run dev          # Tests the compiled library package locally!

Install from Local Path (In your own App)

# Point directly to your local clone of loader-overlay
npm install file:../loader-overlay  # npm 
yarn add ../loader-overlay          # yarn
pnpm add ../loader-overlay          # pnpm

Install from Tarball

# In loader-overlay dir
npm pack                            # creates loader-overlay-x.x.x.tgz

# In your app
npm install ../loader-overlay/loader-overlay-1.0.0.tgz

Install from GitHub

npm install swapnilhpatil/loader-overlay-plugin        # latest
npm install swapnilhpatil/loader-overlay-plugin#v1.0.0 # specific tag

See SETUP_GUIDE.md for the full local installation guide including workspaces, path aliases, and pnpm/yarn link methods.

🚀 Quick Start

import { useState } from 'react';
import LoaderOverlay from 'loader-overlay';

export default function App() {
  const [loading, setLoading] = useState(false);

  const fetchData = async () => {
    setLoading(true);
    await fetch('/api/data');
    setLoading(false);
  };

  return (
    <div style={{ position: 'relative' }}>
      <LoaderOverlay show={loading} />
      <button onClick={fetchData}>Load Data</button>
    </div>
  );
}

📥 Imports

// Default import
import LoaderOverlay from 'loader-overlay';

// Named imports — tree-shakeable (icons & constants)
import { SpinIcon, DotsIcon, PulseIcon, RingIcon, BarIcon } from 'loader-overlay';
import { SIZES, VARIANTS, ANIM_CSS, ICONS } from 'loader-overlay';

// TypeScript — no @types package needed, types are bundled
import type { LoaderOverlayProps, LoaderType, LoaderVariant, LoaderSize } from 'loader-overlay';

📖 Usage Examples

With Progress Bar

<LoaderOverlay
  show={uploading}
  type="bar"
  variant="gradient"
  color="#60d394"
  message="Uploading file..."
  showProgress
  progress={uploadPercent}
/>

Outside Click Dismiss

<LoaderOverlay
  show={loading}
  fullScreen
  closeOnOutsideClick
  closable
  onClose={() => setLoading(false)}
  message="Processing..."
/>

Auto-dismiss with Timeout

<LoaderOverlay
  show={loading}
  timeout={3000}
  onClose={() => setLoading(false)}
  message="Done in 3 seconds..."
  type="dots"
/>

Custom Children

<LoaderOverlay show={loading} variant="dark">
  <div style={{ textAlign: 'center' }}>
    <img src="/logo-animated.svg" width={64} alt="loading" />
    <p style={{ color: 'white' }}>Brewing your dashboard ☕</p>
  </div>
</LoaderOverlay>

TypeScript

import LoaderOverlay, { LoaderOverlayProps } from 'loader-overlay';

const props: LoaderOverlayProps = {
  show: true,
  type: 'spinner',
  variant: 'dark',
  color: '#a78bfa',
};

🎛️ Props Reference

| Prop | Type | Default | Description | |------|------|---------|-------------| | show | boolean | true | Controls loader overlay visibility | | type | 'spinner' \| 'dots' \| 'pulse' \| 'ring' \| 'bar' | 'spinner' | Selection of loader animation type | | size | 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | Configures the size footprint of the loader | | variant | 'dark' \| 'light' \| 'blur' \| 'transparent' \| 'gradient' | 'dark' | Defines the overlay background aesthetic | | color | string | '#a78bfa' | Master accent color (hex, rgb, or css var) | | message | string | 'Loading...' | Primary status label | | submessage | string | '' | Secondary hint or details text | | fullScreen | boolean | false | Fixes overlay relative to viewport vs parent | | zIndex | number | 999 | Determines the CSS z-index | | opacity | number | 1 | Configures the global backdrop opacity | | blur | number | 8 | Frosts the backdrop via CSS blur (px) | | position | 'center' \| 'top' \| 'bottom' | 'center' | Vertical alignment of the main content box | | showProgress | boolean | false | Activates an animated precise progress bar | | progress | number | 0 | Progress value injected into the bar (0–100) | | closable | boolean | false | Displays a dismiss ✕ button in the corner | | onClose | () => void | () => {} | Event fired exactly when the overlay unmounts | | closeOnOutsideClick | boolean | false | Allows backdrop clicks to dismiss the loader | | onOutsideClick | () => void | () => {} | Granular event fired on backdrop interaction | | animateIn | boolean | true | Allows smooth CSS fade-in animations on mount | | timeout | number | 0 | Automatic unmount dismissal after specified ms | | children | ReactNode | null | Drops in totally generic DOM replacing core icons |

🔧 Reusable Hook

import { useState, useCallback } from 'react';
import LoaderOverlay from 'loader-overlay';

function useLoader() {
  const [state, setState] = useState({
    show: false,
    message: 'Loading...',
    progress: 0,
  });

  const start = useCallback((message = 'Loading...') => {
    setState({ show: true, message, progress: 0 });
  }, []);

  const setProgress = useCallback((progress: number) => {
    setState(s => ({ ...s, progress }));
  }, []);

  const stop = useCallback(() => {
    setState(s => ({ ...s, show: false }));
  }, []);

  return { loaderProps: state, start, setProgress, stop };
}

// Usage
function MyPage() {
  const { loaderProps, start, stop } = useLoader();

  return (
    <>
      <LoaderOverlay {...loaderProps} showProgress fullScreen />
      <button onClick={() => { start('Saving...'); setTimeout(stop, 2000); }}>
        Save
      </button>
    </>
  );
}

🌐 Route Transitions (React Router v6)

import { useNavigation, Outlet } from 'react-router-dom';
import LoaderOverlay from 'loader-overlay';

export default function RootLayout() {
  const navigation = useNavigation();

  return (
    <>
      <LoaderOverlay
        show={navigation.state !== 'idle'}
        fullScreen
        type="dots"
        variant="dark"
        message="Navigating..."
        zIndex={9999}
      />
      <Outlet />
    </>
  );
}

📁 Package Structure

loader-overlay/
├── dist/
│   ├── loader-overlay.d.ts          ← TypeScript declarations
│   ├── loader-overlay.es.js         ← ES module (tree-shakeable)
│   ├── loader-overlay.es.js.map     ← Source map
│   ├── loader-overlay.umd.js        ← UMD for CommonJS / CDN use
│   └── loader-overlay.umd.js.map    ← Source map
├── src/
│   ├── index.jsx                    ← Main component entry
│   └── index.d.ts                   ← TypeScript source declarations
├── README.md
└── package.json

📝 Changelog

See CHANGELOG.md for full version history.

🤝 Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b feat/my-feature
3. Commit your changes: git commit -m 'feat: add my feature'
4. Push to the branch: git push origin feat/my-feature
5. Open a Pull Request

👤 Author

Swapnil Patil