Next Js TopLoader

• A Next.js Top Loading Bar component made using nprogress, works with Next.js 14 and React.

Install

using npm:

npm install nextjs-toploader

using yarn:

yarn add nextjs-toploader

Usage

import using:

import NextTopLoader from 'nextjs-toploader';

Usage with app/layout.js for app folder structure

For rendering add <NextTopLoader /> to your return() inside the <body></body> of RootLayout():

import NextTopLoader from 'nextjs-toploader';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <NextTopLoader />
        {children}
      </body>
    </html>
  );
}

Usage with pages/_app.js for pages folder structure

For rendering add <PagesTopLoader /> to your return() in MyApp() (Recommended):

import { PagesTopLoader } from 'nextjs-toploader/pages';

export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <PagesTopLoader />
      <Component {...pageProps} />;
    </>
  );
}

You can also use <NextTopLoader /> in pages router, but it's recommended to use <PagesTopLoader /> for useRouter hook support from nextjs-toploader version 2.6.12 onwards

Compatibility with useRouter hook

useRouter hook usage with app/layout.js for app folder structure

For triggering TopLoader when using useRouter hook (app router):

// Import the useRouter hook from nextjs-toploader to trigger the TopLoader

import { useRouter } from 'nextjs-toploader/app';

Then simply use it in your code for example:

const router = useRouter();
router.push('/some-page');

useRouter hook usage with pages/_app.js for pages folder structure

For triggering TopLoader when using useRouter add <PagesTopLoader /> to your return() in MyApp() :

import { PagesTopLoader } from 'nextjs-toploader/pages';

export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <PagesTopLoader />
      <Component {...pageProps} />;
    </>
  );
}

---

useTopLoader Hook

A custom hook for handling progress indicators using NextTopLoader.

Methods

Example Usage

'use client';

import React from 'react';
import { useTopLoader } from 'nextjs-toploader';

const Component = () => {
  const loader = useTopLoader();
  return (
    <div>
      <button type="button" onClick={() => loader.start()}>
        Start
      </button>
      <button type="button" onClick={() => loader.setProgress(0.5)}>
        Set Progress
      </button>
    </div>
  );
};

export default Component;

---

Usage with React, Vite React or any other React Based Framework

For rendering add <NextTopLoader /> to your return() inside the component in App() in your App.js:

import NextTopLoader from 'nextjs-toploader';
const App = () => {
  return (
    <div>
      <Router>
        <NextTopLoader />
        <Routes>{/* Your Routes Here */}</Routes>
      </Router>
    </div>
  );
};

export default App;

Default Configuration

If no props are passed to <NextTopLoader />, below is the default configuration applied.

<NextTopLoader
  color="#2299DD"
  initialPosition={0.08}
  crawlSpeed={200}
  height={3}
  crawl={true}
  showSpinner={true}
  easing="ease"
  speed={200}
  shadow="0 0 10px #2299DD,0 0 5px #2299DD"
  template='<div class="bar" role="bar"><div class="peg"></div></div> 
  <div class="spinner" role="spinner"><div class="spinner-icon"></div></div>'
  zIndex={1600}
  showAtBottom={false}
/>

• color: to change the default color of TopLoader.
• initialPosition: to change initial position for the TopLoader in percentage, : 0.08 = 8%.
• crawlSpeed: increment delay speed in ms.
• speed: animation speed for the TopLoader in ms
• easing: animation settings using easing (a CSS easing string).
• height: height of TopLoader in px.
• crawl: auto incrementing behavior for the TopLoader.
• showSpinner: to show spinner or not.
• shadow: a smooth shadow for the TopLoader. (set it to false to disable it)
• template: to include custom HTML attributes for the TopLoader.
• zIndex: defines zIndex for the TopLoader.
• showAtBottom: to show the TopLoader at bottom. (increase height for the TopLoader to ensure it's visibility at the mobile devices).
• showForHashAnchor: to show for "#" url or not. (set it to false to disable it).
• nonce: to add nonces to the <style> tags, for Content Security Policy (might require skipping SSR to avoid a hydration error).

NextTopLoaderProps (props passed to the TopLoader)

Contributors

Code Contributors

This project was made possible thanks to the contributions of its code contributors.

Financial Contribution

---