You're Invited: Meet the Socket team at BSidesSF and RSAC - April 27 - May 1.RSVP →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

nextjs-toploader

Package Overview
Dependencies
Maintainers
1
Versions
24
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

nextjs-toploader

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

3.8.16
latest
Source
npm
Version published
Weekly downloads
171K
0.48%
Maintainers
1
Weekly downloads
 
Created
Source

NextJS TopLoader Next Js TopLoader

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

NPM NPM Downloads

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

NameDescription
startStarts the progress bar
doneCompletes the progress bar. Can be forced to complete immediately with an optional force parameter
removeRemoves the progress bar element from the DOM
setProgressManually sets the progress value (between 0.0 and 1.0)
incIncrements the progress bar by a specified amount. If no amount is specified, it makes a small automatic increment
trickleAdds small random increments to the progress bar
isStartedChecks if the progress bar has been started
isRenderedChecks if the progress bar is rendered in the DOM
getPositioningCSSReturns 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 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)
NextTopLoaderProps (props passed to the TopLoader)
NameTypeDefault Value
colorstring"#2299DD"
initialPositionnumber0.08
crawlSpeednumber200
heightnumber3
crawlbooleantrue
showSpinnerbooleantrue
easingstring"ease"
speednumber200
shadowstring | false"0 0 10px #2299DD,0 0 5px #2299DD"
templatestring"<div class="bar" role="bar"><div class="peg"></div></div><div class="spinner" role="spinner"><div class="spinner-icon"></div></div>"
zIndexnumber1600
showAtBottombooleanfalse
showForHashAnchorbooleantrue

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)

Sponsor me on GitHub

"Buy Me A Coffee"

OpenCollective

Keywords

Next
Next TopLoader
Next.js
Next.js 15
Next.js 14
Next.js 13

FAQs

Package last updated on 25 Mar 2025

Did you know?

Socket

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.

Install

Related posts

Malicious npm Package Disguised as Advcash Integration Triggers Reverse Shell

Research

Malicious npm Package Disguised as Advcash Integration Triggers Reverse Shell

The Socket Research Team investigates a malicious npm package that appears to be an Advcash integration but triggers a reverse shell during payment success, targeting servers handling transactions.

By Socket Research Team, Sarah Gooding  -  Apr 14, 2025
Turtles, Clams, and Cyber Threat Actors: Shell Usage

Security Fundamentals

Turtles, Clams, and Cyber Threat Actors: Shell Usage

The Socket Threat Research Team uncovers how threat actors weaponize shell techniques across npm, PyPI, and Go ecosystems to maintain persistence and exfiltrate data.

By Olivia Brown, Kirill Boychenko  -  Apr 11, 2025