react-hook-loading-spinner

A lightweight and flexible React loading state hook library with built-in spinner components, global state management, and zero dependencies (except React and Zustand).

Installation

``bash
npm install @rokku-x/react-hook-loading-spinner
`

Features

- 🎯 Global Loading State - Centralized loading management across your entire app
- 🪝 React Hooks API - Easy-to-use hook-based interface with automatic cleanup
- 🔄 Reference Counting - Multiple components can start/stop loading independently
- ⚡ Async/Await Support - Built-in async wrapper for promises
- 🎨 Customizable Spinners - Pre-built components or bring your own
- 📦 TypeScript Support - Full type safety out of the box
- 🎭 Multiple Animations - Spin, fade, or no animation
- 📡 Event System - Subscribe to loading state changes
- ♿ Accessibility - Built-in inert attribute and scroll prevention
- 📱 Zero Dependencies - Only requires React and Zustand

Bundle Size

- ESM: 4.23 kB gzipped (12.80 kB raw)
- CJS: 3.67 kB gzipped (9.31 kB raw)

Runtime Performance

- startLoading(): 0.025ms per operation
- stopLoading(): 0.0006ms per operation
- start/stop cycle: 0.023ms per cycle
- asyncUseLoading(): 0.076ms per operation (overhead)
- overrideLoading(): 0.011ms per operation
- 10 instances start/stop: 0.269ms per cycle

All measurements are extremely fast, with even 1000 operations completing in milliseconds. Measurements based on actual benchmarks in test suite.

Quick Start

$3

First, add the LoadingRenderer at the root of your application:

`tsx
import { LoadingRenderer } from '@rokku-x/react-hook-loading-spinner';

function App() {
return (
<>



);
}
`

$3

`tsx
import { useLoading } from '@rokku-x/react-hook-loading-spinner';

function MyComponent() {
const { startLoading, stopLoading, isLoading } = useLoading();

const handleClick = async () => {
startLoading();
try {
await fetchData();
} finally {
stopLoading();
}
};

return (

{isLoading ? 'Loading...' : 'Fetch Data'}

);
}
`

API Reference

$3

The main component that renders the loading spinner overlay. Must be mounted at the root level.

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| loadingComponent | React.ComponentType \| React.ReactElement | LoadingCircle | Custom loading component to display |
| loadingComponentScale | number | 1 | Scale factor for the loading component |
| animationType | AnimationType | AnimationType.Spin | Animation type: 'spin', 'fadeInOut', or 'none' |
| animationDuration | number | 1 (spin) or 2 (fade) | Animation duration in seconds |
| wrapperStyle | CSSProperties | undefined | Inline styles for the dialog wrapper |
| wrapperClassName | string | undefined | CSS class for the dialog wrapper |
| wrapperId | string | 'loading-wrapper-{random}' | Unique identifier for the wrapper |
| animationWrapperStyle | CSSProperties | undefined | Inline styles for the animation wrapper |
| animationWrapperClassName | string | undefined | CSS class for the animation wrapper |
| animationWrapperId | string | undefined | ID for the animation wrapper |

#### Built-in Loading Components

| Component | Description |
|-----------|-------------|
| LoadingCircle | Spinning circle spinner (default) |
| LoadingPleaseWait | "Please wait..." text |

$3

Hook for managing loading state in your components.

#### Returns

`typescript
{
startLoading: () => void,
stopLoading: () => void,
asyncUseLoading: (promise: Promise) => Promise,
overrideLoading: (state: boolean | null) => void,
isLoading: boolean,
isLocalLoading: boolean
}
`

| Return Value | Type | Description |
|---|---|---|
| startLoading | () => void | Increment the loading counter (starts loading) |
| stopLoading | () => void | Decrement the loading counter (stops loading when reaches 0) |
| asyncUseLoading | (promise: Promise) => Promise | Wrap a promise to automatically manage loading state |
| overrideLoading | (state: boolean \| null) => void | Override the loading state (null = remove override) |
| isLoading | boolean | Global loading state (true if any component is loading) |
| isLocalLoading | boolean | Local loading state for this hook instance only |

$3

A component that triggers loading state based on a prop.

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| isLoading | boolean | false | Whether to show loading state |

#### Example

`tsx
import { Loading } from 'react-hook-loading-spinner';

function MyComponent() {
const [fetching, setFetching] = useState(false);

return (
<>

{/ Your component /}

);
}
`

$3

`typescript
const AnimationType = {
Spin: 'spin',
FadeInOut: 'fadeInOut',
None: 'none',
} as const;
`

$3

Event emitter for subscribing to loading state changes.

#### Events

| Event | Payload | Description |
|-------|---------|-------------|
| 'change' | { isLoading: boolean, isOverrideState: boolean } | Emitted whenever loading state changes |
| 'start' | null | Emitted when loading starts (transitions from false to true) |
| 'stop' | null | Emitted when loading stops (transitions from true to false) |

#### Example

`tsx
import { loadingEventTarget } from 'react-hook-loading-spinner';

useEffect(() => {
const listener = loadingEventTarget.on('change', ({ isLoading }) => {
console.log('Loading state changed:', isLoading);
});

return () => listener.removeAllListeners();
}, []);
`

Examples

$3

`tsx
import { useLoading, LoadingRenderer } from 'react-hook-loading-spinner';

function App() {
return (
<>



);
}

function BasicLoadingExample() {
const { startLoading, stopLoading } = useLoading();

const handleFetch = async () => {
startLoading();
try {
await fetch('https://api.example.com/data');
} finally {
stopLoading();
}
};

return Fetch Data;
}
`

$3

The asyncUseLoading method automatically manages loading state for promises.

`tsx
import { useLoading, LoadingRenderer } from 'react-hook-loading-spinner';

function AsyncExample() {
const { asyncUseLoading } = useLoading();

const handleFetch = async () => {
// Loading state is automatically managed
const data = await asyncUseLoading(
fetch('https://api.example.com/data').then(res => res.json())
);
console.log(data);
};

return Fetch Data;
}

function App() {
return (
<>



);
}
`

$3

Multiple components can start loading independently. The loading indicator stays visible until all have stopped.

`tsx
import { useLoading, LoadingRenderer } from 'react-hook-loading-spinner';

function MultipleLoadingExample() {
const { asyncUseLoading } = useLoading();

const fetchUser = () => asyncUseLoading(
fetch('https://api.example.com/user').then(res => res.json())
);

const fetchPosts = () => asyncUseLoading(
fetch('https://api.example.com/posts').then(res => res.json())
);

const fetchAll = async () => {
// Both requests will show loading
// Loading stops when both complete
await Promise.all([fetchUser(), fetchPosts()]);
};

return (


function App() {
return (
<>



);
}
`

$3

Track loading state for individual components without affecting global state visibility.

`tsx
import { useLoading, LoadingRenderer } from 'react-hook-loading-spinner';

function LocalLoadingExample() {
const { startLoading, stopLoading, isLocalLoading } = useLoading();

const handleClick = async () => {
startLoading();
try {
await fetch('https://api.example.com/data');
} finally {
stopLoading();
}
};

return (

{isLocalLoading ? 'Loading...' : 'Fetch Data'}

);
}

function App() {
return (
<>



);
}
`

$3

Force loading state on or off, bypassing the reference counting.

`tsx
import { useLoading, LoadingRenderer } from 'react-hook-loading-spinner';

function OverrideExample() {
const { overrideLoading, isLoading } = useLoading();

const forceLoading = () => overrideLoading(true);
const clearOverride = () => overrideLoading(null);

return (


function App() {
return (
<>



);
}
`

$3

`tsx
import { LoadingRenderer } from 'react-hook-loading-spinner';

const CustomSpinner = () => (