README.md

next-loading-box

React component designed for Next.js to manage route change loading states.

⚠️ This component is designed for the Pages Router in Next.js. If you're using the App Router, it provides built-in support for Loading UI. For more information, refer to the Next.js documentation on Loading UI and Streaming.

📄 Motivation

Next.js applications using server-side rendering (SSR) can sometimes experience delays due to complex computations, data fetching, or large payloads. These delays can result in users waiting without visual feedback during page navigation, leading to a poor user experience.

next-loading-box addresses this issue by providing an intuitive and customizable loading wrapper that integrates seamlessly with Next.js routing.

Key benefits of using next-loading-box:

1. Simplifies loading state management
2. Eliminates the need for extensive boilerplate code
3. Allows any component to be used as a loading indicator
4. Offers configurable animation delays
5. Provides instant feedback during slow prerendering

By implementing next-loading-box, you can enhance the perceived performance of your application, keeping users engaged and informed about ongoing processes during navigation.

⚙️ Installation

Install the package using one of the following commands:

npm install next-loading-box
# or
pnpm install next-loading-box
# or
yarn add next-loading-box

🚀 Usage

Scoped Loader (For e.g. Spinner, Overlay, etc.)

A "scoped loader" is used for displaying loading indicators within specific components during navigation:

import { LoadingBox } from 'next-loading-box';

const MyComponent = () => {
  return (
    <div>
      <h1>My Component</h1>
      <LoadingBox loading={<Spinner />}>
        <Link href="/slow-page">With Loader</Link>
      </LoadingBox>
    </div>
  );
};

Global Loader with Path Patterns

You can use different loading components based on route patterns using regular expressions:

// _app.tsx
import { LoadingBox } from 'next-loading-box';
import type { AppProps } from 'next/app';

const loaders = [
  {
    pattern: /^\/blog/, // Matches all blog routes
    component: <BlogSkeleton />,
  },
  {
    pattern: /^\/products\/[^/]+$/, // Matches /products/{id}
    component: <ProductSkeleton />,
  },
  {
    pattern: /.*/, // Fallback loader for all routes
    component: <DefaultLoader />,
  },
];

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <LoadingBox loading={loaders} global>
      <Component {...pageProps} />
    </LoadingBox>
  );
}

Global Loader with Overlay

To show loading components alongside content (e.g., for progress bars):

// _app.tsx
import { LoadingBox } from 'next-loading-box';
import type { AppProps } from 'next/app';

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <LoadingBox loading={<TopProgressBar />} global overlay>
      <Component {...pageProps} />
    </LoadingBox>
  );
}

🔧 Props

Prop	Type	Default	Description
loading	React.ReactNode | PathPattern[]	-	Loading component or path-based loading components
children	React.ReactNode	-	Content to wrap
delay	number	0	Delay in milliseconds before showing loading state
style	CSSProperties	-	CSS styles for wrapper
className	string	-	CSS class for wrapper
shallow	boolean	false	Whether to show loading on shallow route changes
global	boolean	false	Whether this is a global loading handler
overlay	boolean	false	For global loaders, whether to show loading alongside content

PathPattern Type

interface PathPattern {
  pattern: RegExp; // Regular expression to match the route path
  component: React.ReactNode; // Loading component to show
}

📄 License

next-loading-box is MIT licensed.