npm package: @klazapp/loading-overlay
Description: A reusable React loading overlay component with blur effect and customizable spinner
Latest version: 1.0.3

# @klazapp/loading-overlay

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

## Installation

```bash
npm install @klazapp/loading-overlay
```

## Quick Start

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

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

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

### Overlay Appearance

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

### Tailwind / CSS Classes

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

### Inline Styles

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

### Custom Spinner

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

### Loading Text

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

## Standalone Spinners

Use spinners independently:

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

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