🚀 Next.js Loader

The modern loading system for Next.js. Beautiful progress bars, spinners, overlays, skeletons, and adaptive loaders with automatic route detection—no manual start/stop calls required.

✨ Why Next.js Loader?

Building loading indicators for the App Router usually means wiring up route events, managing concurrent navigations, handling race conditions, preventing flicker, and creating polished animations.

Next.js Loader handles all of that for you.

Simply install the package, add a single component, and your application instantly gets beautiful loading indicators during navigation.

<NextLoader />

No router events.

No manual start() or done().

No boilerplate.

✨ Features

• 🚀 Automatic route navigation detection
• 📊 Animated top progress bar
• 🌀 Spinner loader
• 💍 Ring loader
• ⚪ Dots loader
• 🌫 Full-screen overlay loader
• 🦴 Skeleton loader
• 🎨 Built-in light, dark & system themes
• ⚡ Adaptive loader mode
• 🛡 Navigation timeout protection
• ⏱ Minimum display duration
• 🧠 Concurrent navigation handling
• 🔌 Plugin architecture
• ♿ Accessibility-first
• 🌳 Tree-shakable
• 💙 TypeScript support
• 📦 Zero runtime dependencies

Installation

npm install nextjs-loader

or

yarn add nextjs-loader

or

pnpm add nextjs-loader

Quick Start

Add NextLoader inside your root layout.

import { NextLoader } from "nextjs-loader";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <NextLoader />
        {children}
      </body>
    </html>
  );
}

That's it.

Your application now automatically displays a loading indicator whenever users navigate between pages.

Multiple Loader Variants

You can combine multiple loaders together.

<NextLoader
  variants={[
    "bar",
    "spinner",
    "overlay"
  ]}
/>

Supported variants:

• "bar"
• "spinner"
• "ring"
• "dots"
• "overlay"
• "skeleton"

Top Progress Bar

<NextLoader
  variants={["bar"]}
  bar={{
    color: "#2563eb",
    height: 3,
    speed: 200,
    crawl: true,
    crawlSpeed: 300,
    easing: "ease-out",
    shadow: true,
  }}
/>

Spinner

<NextLoader
  variants={["spinner"]}
  spinner={{
    position: "center",
    size: 60,
    color: "#2563eb",
  }}
/>

Supported positions:

• center
• top-left
• top-right
• bottom-left
• bottom-right

Ring

<NextLoader
  variants={["ring"]}
  ring={{
    size: 50,
    color: "#2563eb",
  }}
/>

Dots

<NextLoader
  variants={["dots"]}
  dots={{
    size: 10,
    color: "#2563eb",
  }}
/>

Overlay

<NextLoader
  variants={["overlay"]}
  overlay={{
    opacity: 0.5,
    blur: true,
  }}
/>

Skeleton

<NextLoader
  variants={["skeleton"]}
/>

Adaptive Loader

Automatically chooses the best loading animation depending on the navigation state.

<NextLoader adaptive />

Or configure it:

<NextLoader
  adaptive={{
    strategy: "smart",
  }}
/>

Themes

Light

<NextLoader theme="light" />

Dark

<NextLoader theme="dark" />

System

<NextLoader theme="system" />

Custom Theme

<NextLoader
  theme={{
    primary: "#2563eb",
    background: "#ffffff",
    text: "#111827",
  }}
/>

Prevent Flickering

Keep the loader visible for at least a minimum duration.

<NextLoader
  minDisplayMs={300}
/>

Navigation Timeout

Automatically hide the loader if navigation takes too long.

<NextLoader
  timeoutMs={5000}
/>

Accessibility

<NextLoader
  a11yLabel="Loading page"
/>

Built-in accessibility includes:

• Screen reader support
• ARIA labels
• Keyboard-friendly behaviour
• Reduced motion support

Plugins

Extend the loader with your own plugins.

<NextLoader
  plugins={[
    myPlugin,
  ]}
/>

API

| Prop | Type | Default | | -------------- | ---------------------------- | ---------------- | | variants | LoaderVariant[] | ["bar"] | | bar | TopBarProps | — | | spinner | SpinnerProps | — | | ring | RingProps | — | | dots | DotsProps | — | | overlay | OverlayProps | — | | skeleton | SkeletonProps | — | | adaptive | boolean \| AdaptiveOptions | false | | theme | ThemeName \| ThemeTokens | "system" | | plugins | LoaderPlugin[] | [] | | minDisplayMs | number | 200 | | timeoutMs | number | 4000 | | a11yLabel | string | "Page loading" |

TypeScript

Fully typed with first-class TypeScript support.

import type { NextLoaderProps } from "nextjs-loader";

Compatibility

| Technology | Supported | | ---------- | --------- | | Next.js 13 | ✅ | | Next.js 14 | ✅ | | Next.js 15 | ✅ | | Next.js 16 | ✅ | | React 18 | ✅ | | React 19 | ✅ | | TypeScript | ✅ |

Performance

• Zero runtime dependencies
• Tree-shakable
• Lazy-loaded renderers
• Optimised rendering
• Concurrent navigation support
• Lightweight footprint
• Built for the App Router

Browser Support

• ✅ Chrome
• ✅ Edge
• ✅ Firefox
• ✅ Safari

Comparison

| Feature | Next.js Loader | Traditional Progress Bars | | ------------------------------ | :------------: | :-----------------------: | | Automatic navigation detection | ✅ | ❌ | | App Router support | ✅ | ⚠️ | | Progress bar | ✅ | ✅ | | Spinner | ✅ | ❌ | | Overlay | ✅ | ❌ | | Skeleton | ✅ | ❌ | | Adaptive loader | ✅ | ❌ | | Theme support | ✅ | ❌ | | Accessibility | ✅ | ⚠️ | | TypeScript | ✅ | ⚠️ | | React 19 support | ✅ | ⚠️ |

Roadmap

• [ ] Promise API
• [ ] Automatic Fetch API tracking
• [ ] Axios integration
• [ ] React Query integration
• [ ] SWR integration
• [ ] Progress percentage
• [ ] Loading messages
• [ ] Built-in presets
• [ ] Analytics
• [ ] DevTools
• [ ] Custom renderer API

Contributing

Contributions are always welcome!

1. Fork the repository
2. Create a feature branch

git checkout -b feature/amazing-feature

3. Commit your changes

git commit -m "Add amazing feature"

4. Push your branch

git push origin feature/amazing-feature

5. Open a Pull Request

License

MIT © Rohan Vimal

Support

If this package helps your project, please consider:

⭐ Starring the repository

🐞 Reporting bugs

💡 Suggesting new features

🤝 Contributing to the project

Made with ❤️ for the Next.js community.