@klazapp/loading-overlay

A customizable React loading overlay with blur effect and modern spinner animations.

Installation

npm install @klazapp/loading-overlay

Quick Start

import { LoadingOverlay } from "@klazapp/loading-overlay";

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

  return (
    <div style={{ position: "relative" }}>
      <YourContent />
      <LoadingOverlay isLoading={loading} />
    </div>
  );
}

Spinner Variants

Three built-in spinner styles:

<LoadingOverlay isLoading={true} variant="ring" />   // Gradient ring (default)
<LoadingOverlay isLoading={true} variant="dots" />   // Bouncing dots
<LoadingOverlay isLoading={true} variant="pulse" />  // Pulsing circles

Customization

Colors & Size

<LoadingOverlay
  isLoading={true}
  spinnerSize={64}
  spinnerColor="#10b981" // Primary color
  spinnerSecondaryColor="#06b6d4" // Gradient secondary
  spinnerSpeed={1.5} // Animation speed (1 = normal)
/>

Overlay Appearance

<LoadingOverlay
  isLoading={true}
  backgroundOpacity={60} // 0-100
  blurAmount={4} // pixels (0 to disable)
  enableBackdropBlur={false} // disable blur entirely
  zIndex={100}
/>

Tailwind / CSS Classes

<LoadingOverlay
  isLoading={true}
  className="rounded-xl" // Overlay container
  spinnerClassName="drop-shadow-xl" // Spinner container
/>

Inline Styles

<LoadingOverlay
  isLoading={true}
  style={{ borderRadius: 12 }}
  spinnerStyle={{ filter: "drop-shadow(0 0 10px blue)" }}
/>

Custom Spinner

<LoadingOverlay isLoading={true} customSpinner={<MyCustomSpinner />} />

Loading Text

<LoadingOverlay isLoading={true} loadingText="Loading..." textColor="white" />

Standalone Spinners

Use spinners independently:

import { RingSpinner, DotsSpinner, PulseSpinner } from '@klazapp/loading-overlay';

<RingSpinner size={32} color="#3b82f6" />
<DotsSpinner size={24} color="#10b981" speed={0.8} />
<PulseSpinner size={48} color="#8b5cf6" className="my-spinner" />

Minimum Loading Time Hook

Prevent jarring flash for fast operations:

import { LoadingOverlay, useMinLoadingTime } from "@klazapp/loading-overlay";

function App() {
  const [dataLoading, setDataLoading] = useState(false);
  const showLoading = useMinLoadingTime(dataLoading, { minTime: 300 });

  return (
    <div style={{ position: "relative" }}>
      <Content />
      <LoadingOverlay isLoading={showLoading} />
    </div>
  );
}

Props Reference

LoadingOverlayProps

| Prop | Type | Default | Description | | ----------------------- | ----------------------------- | ------------------------- | -------------------------------------- | | isLoading | boolean | required | Show/hide overlay | | variant | 'ring' \| 'dots' \| 'pulse' | 'ring' | Spinner style | | spinnerSize | number | 48 | Size in pixels | | spinnerColor | string | '#3b82f6' | Primary color | | spinnerSecondaryColor | string | '#8b5cf6' | Gradient color | | spinnerSpeed | number | 1 | Animation speed multiplier | | backgroundOpacity | number | 40 | Overlay opacity (0-100) | | blurAmount | number | 2 | Backdrop blur in pixels (0 to disable) | | enableBackdropBlur | boolean | true | Enable/disable backdrop blur | | zIndex | number | 50 | CSS z-index | | className | string | '' | Overlay CSS class | | spinnerClassName | string | '' | Spinner CSS class | | style | CSSProperties | {} | Overlay inline styles | | spinnerStyle | CSSProperties | {} | Spinner inline styles | | customSpinner | ReactNode | - | Custom spinner component | | loadingText | string | - | Text below spinner | | textColor | string | 'rgba(255,255,255,0.7)' | Text color |

SpinnerProps

| Prop | Type | Default | Description | | ---------------- | --------------- | ----------- | --------------- | | size | number | 48 | Size in pixels | | color | string | '#3b82f6' | Primary color | | secondaryColor | string | '#8b5cf6' | Gradient color | | speed | number | 1 | Animation speed | | className | string | '' | CSS class | | style | CSSProperties | {} | Inline styles |

License

MIT