Product
Introducing Reports: An Extensible Reporting Framework for Socket Data
Explore exportable charts for vulnerabilities, dependencies, and usage with Reports, Socket’s new extensible reporting framework.
By André Staltz - Apr 21, 2026
Launch Week Day 1: Socket for Jira Is Now Available.Learn More →
nextjs-toploader
Advanced tools
nextjs-toploader
A Next.js Top Loading Bar component made using nprogress, works with Next.js 15 and Next.js 14 and React.
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 (
<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 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)
Other packages similar to nextjs-toploader
nprogress
NProgress is a popular package for creating a progress bar at the top of the page. It is not specific to Next.js and can be used in any JavaScript application. Compared to nextjs-toploader, NProgress offers more customization options and is widely used, but requires more setup to integrate with Next.js.
react-top-loading-bar
React Top Loading Bar is a React component for displaying a loading bar at the top of the page. It is similar to nextjs-toploader in terms of functionality but is designed for use in any React application, not just Next.js. It provides a simple API for controlling the loading bar programmatically.
FAQs
A Next.js Top Loading Bar component made using nprogress, works with Next.js 15 and Next.js 14 and React.
The npm package nextjs-toploader receives a total of 329,505 weekly downloads. As such, nextjs-toploader popularity was classified as popular.
We found that nextjs-toploader demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Package last updated on 09 Sep 2025
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Related posts
Product
Socket for Jira Is Now Available
Socket for Jira lets teams turn alerts into Jira tickets with manual creation, automated ticketing rules, and two-way sync.
By Jeppe Hasseriis - Apr 20, 2026
Company News
Socket Named Top Sales Organization by RepVue
Socket won two 2026 Reppy Awards from RepVue, ranking in the top 5% of all sales orgs. AE Alexandra Lister shares what it's like to grow a sales career here.
By Sarah Gooding - Apr 17, 2026