Skip to content

Latest commit

 

History

History
214 lines (156 loc) · 8.28 KB

JSR.md

File metadata and controls

214 lines (156 loc) · 8.28 KB
Raw

Next Js TopLoader

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

NPM NPM Downloads JSR

For using npm package manager instead see: (https://www.npmjs.com/package/@thesgj/nextjs-toploader)

Install

using jsr with npm:

npx jsr add @thesgj/@thesgj/nextjs-toploader

using jsr with yarn:

yarn dlx jsr add @thesgj/@thesgj/nextjs-toploader

using deno:

deno add @thesgj/@thesgj/nextjs-toploader

Usage

import using:

import NextTopLoader from '@thesgj/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 '@thesgj/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 '@thesgj/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 @thesgj/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 @thesgj/nextjs-toploader to trigger the TopLoader

import { useRouter } from '@thesgj/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 '@thesgj/nextjs-toploader/pages';

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

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 '@thesgj/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 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)

NextTopLoaderProps (props passed to the TopLoader)

Name Type Default Value
color string "#29d"
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 ${color}, 0 0 5px ${color}"
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

Contributors

Code Contributors

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

Financial Contributors

We extend a huge thanks to our financial contributor for helping us sustain this community

Sentry

Support this project with your organization. Your logo will show up here with a link to your website. You can Support this project on Open Collective or Equivalent Method from the below

UPI ID: thesgj@upi (International UPI ID)

Sponsor me on GitHub

"Buy Me A Coffee"

OpenCollective