hub / github.com/TheSGJ/nextjs-toploader

github.com/TheSGJ/nextjs-toploader @v3.9.17

repository ↗ · DeepWiki ↗ · release v3.9.17 ↗ · + Follow

17 symbols 39 edges 6 files 4 documented · 24% 9 cross-repo links ● updated 3mo agov3.9.17 · 2025-09-09★ 1,22935 open issues

What it actually does AI analysis from the code graph — generated when you open this

loading…

README

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

Name	Description
start	Starts the progress bar
done	Completes the progress bar. Can be forced to complete immediately with an optional force parameter
remove	Removes the progress bar element from the DOM
setProgress	Manually sets the progress value (between 0.0 and 1.0)
inc	Increments the progress bar by a specified amount. If no amount is specified, it makes a small automatic increment
trickle	Adds small random increments to the progress bar
isStarted	Checks if the progress bar has been started
isRendered	Checks if the progress bar is rendered in the DOM
getPositioningCSS	Returns the positioning CSS property of the progress bar

Example Usage

'use client';

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

const Component = () => {
  const loader = useTopLoader();
  return (



      <button type="button" onClick={() => loader.start()}>
        Start
      </button>
      <button type="button" onClick={() => loader.setProgress(0.5)}>
        Set Progress
      </button>



  );
};

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 (



      <Router>
        <NextTopLoader />
        <Routes>{/* Your Routes Here */}</Routes>
      </Router>



  );
};

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='
















'
  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)

Name	Type	Default Value
`color`	`string`	`"#2299DD"`
`initialPosition`	`number`	`0.08`
`crawlSpeed`	`number`	`200`
`height`	`number`	`3`
`crawl`	`boolean`	`true`
`showSpinner`	`boolean`	`true`
`easing`	`string`	`"ease"`
`speed`	`number`	`200`
`shadow`	`string \\| false`	`"0 0 10px #2299DD,0 0 5px #2299DD"`
`template`	`string`	`"

Contributors

Code Contributors

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

Financial Contribution

UPI ID: thesgj@upi (International UPI ID)

Extension points exported contracts — how you extend this code

Element (Interface)

(no doc)

deno.d.ts

TopLoaderActions (Interface)

(no doc)

src/hooks/useTopLoader.tsx

Core symbols most depended-on inside this repo

Shape

Function 15

Interface 2

Languages

TypeScript100%

Modules by API surface

src/index.tsx10 symbols

src/pages.tsx3 symbols

src/hooks/useTopLoader.tsx2 symbols

src/app.ts1 symbols

deno.d.ts1 symbols

Used by 9 indexed graphs manifest dependencies, hub-wide

github.com/Dokploy/dokploy

github.com/Kiranism/next-shadcn-dashboard-starter

github.com/Open-Legal-Products/mike

github.com/akdeb/ElatoAI

github.com/fosrl/pangolin

github.com/guildxyz/guild.xyz

github.com/learnhouse/learnhouse

github.com/lobehub/lobehub

github.com/sushi-labs/sushiswap

For agents

$ claude mcp add nextjs-toploader \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact

github.com/TheSGJ/nextjs-toploader @v3.9.17

Next Js TopLoader

Install

Usage

Usage with app/layout.js for app folder structure

Usage with pages/_app.js for pages folder structure

Compatibility with useRouter hook

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

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

useTopLoader Hook

Methods

Example Usage

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

Default Configuration

NextTopLoaderProps (props passed to the TopLoader)

Contributors

Code Contributors

Financial Contribution

Extension points exported contracts — how you extend this code

Core symbols most depended-on inside this repo

Shape

Languages

Modules by API surface

Used by 9 indexed graphs manifest dependencies, hub-wide

For agents

Ask about this repo answers extend the page

Usage with `app/layout.js` for `app` folder structure

Usage with `pages/_app.js` for `pages` folder structure

Compatibility with `useRouter` hook

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

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

`NextTopLoaderProps` (props passed to the TopLoader)