TheSGJ
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-toploaderusing yarn:
yarn add nextjs-toploaderUsage
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 (
<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 <Router><Router/> 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 inms.speed: animation speed for the TopLoader inmseasing: animation settings using easing (a CSS easing string).height: height of TopLoader inpx.crawl: auto incrementing behavior for the TopLoader.showSpinner: to show spinner or not.shadow: a smooth shadow for the TopLoader. (set it tofalseto 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 tofalseto 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 |
"<div class="bar" role="bar"><div class="peg"></div></div><div class="spinner" role="spinner"><div class="spinner-icon"></div></div>" |
|
zIndex |
number |
1600 |
|
showAtBottom |
boolean |
false |
|
showForHashAnchor |
boolean |
true |
|
nonce |
string |
undefined |
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)
