DOCSEARCHbyAlgolia
Submit Docs

nextjs-toploader

repository·master·Indexed 22 days ago

https://github.com/thesgj/nextjs-toploader

A progress bar component built on nprogress for Next.js 14, Next.js 15, and React applications. It provides visual feedback during route transitions and includes specialized components like NextTopLoader for the App Router and PagesTopLoader for the Pages Router, as well as a useTopLoader hook for manual programmatic control.

Tokens
3.6K
Snippets
13
Records
18
Agent score
72%

What's inside nextjs-toploader

  1. Setup PagesTopLoader in Next.js Pages Router

    master

    For projects using the pages folder structure, it is recommended to use PagesTopLoader from the /pages entry point. Add it to your MyApp component in _app.js.

    Note: While <NextTopLoader /> can be used in the pages router, <PagesTopLoader /> is recommended for full useRouter hook support (available from version 2.6.12 onwards).

    import { PagesTopLoader } from '@thesgj/nextjs-toploader/pages';

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

  2. Install NextJs TopLoader via JSR

    master

    You can install the package using JSR with various package managers:

    npm:

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

    yarn:

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

    deno:

    deno add @thesgj/@thesgj/nextjs-toploader

  3. Setup NextTopLoader in Next.js App Router

    master

    For projects using the app folder structure, import NextTopLoader and add it inside the <body> tag of your RootLayout component.

    import NextTopLoader from '@thesgj/nextjs-toploader';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <NextTopLoader />
        {children}
      </body>
    </html>
  );
}

  4. Use PagesTopLoader in Next.js Pages Router

    master

    For projects using the pages/ directory structure, it is recommended to use PagesTopLoader from nextjs-toploader/pages inside your _app.js file to ensure compatibility with the useRouter hook.

    import { PagesTopLoader } from 'nextjs-toploader/pages';

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

  5. Use NextTopLoader in Next.js App Router

    master

    For projects using the app/ directory structure, import NextTopLoader and add it inside the <body> tag of your RootLayout component.

    import NextTopLoader from 'nextjs-toploader';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <NextTopLoader />
        {children}
      </body>
    </html>
  );
}

  6. Use NextTopLoader in React or Vite

    master

    For non-Next.js React applications (like Vite), add <NextTopLoader /> inside your <Router> component.

    import NextTopLoader from '@thesgj/nextjs-toploader';

const App = () => {
  return (
    <div>
      <Router>
        <NextTopLoader />
        <Routes>{/* Your Routes Here */}</Routes>
      </Router>
    </div>
  );
};

export default App;
    import NextTopLoader from '@thesgj/nextjs-toploader';
const App = () => {
  return (
    <div>
      <Router>
        <NextTopLoader />
        <Routes>{/* Your Routes Here */}</Routes>
      </Router>
    </div>
  );
};

export default App;

  7. Use NextTopLoader with React or Vite

    master

    For non-Next.js React environments (like Vite), add <NextTopLoader /> inside your Router component within your main App component.

    import NextTopLoader from 'nextjs-toploader';
const App = () => {
  return (
    <div>
      <Router>
        <NextTopLoader />
        <Routes>{/* Your Routes Here */}</Routes>
      </Router>
    </div>
  );
};

export default App;

  9. Configure NextTopLoader props

    master

    You can customize the appearance and behavior of the loading bar using the following props on <NextTopLoader />:

    NameTypeDefaultDescription
    colorstring"#29d"Changes the color of the bar.
    initialPositionnumber0.08Initial position in percentage (e.g., 0.08 is 8%).
    crawlSpeednumber200Increment delay speed in ms.
    heightnumber3Height of the bar in px.
    crawlbooleantrueEnables auto-incrementing behavior.
    showSpinnerbooleantrueWhether to show the loading spinner.
    easingstring"ease"CSS easing string for animation.
    speednumber200Animation speed in ms.
    shadowstring | false"0 0 10px ${color}, 0 0 5px ${color}"Smooth shadow for the bar. Set to false to disable.
    templatestring(HTML string)Custom HTML template for the bar and spinner.
    zIndexnumber1600The z-index of the loading bar.
    showAtBottombooleanfalseIf true, shows the bar at the bottom of the screen.

  10. Configure NextTopLoader props

    master

    You can customize the appearance and behavior of the <NextTopLoader /> component using the following props.

    | **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` |

  11. Use the useTopLoader hook

    master

    The useTopLoader hook provides manual control over the progress bar. It returns an object containing several methods to manage the loader's state and progress.

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

  12. Trigger TopLoader with useRouter in Pages Router

    master

    To ensure the loading bar triggers when using useRouter in the Pages Router, you must use <PagesTopLoader /> in your _app.js file.

    import { PagesTopLoader } from '@thesgj/nextjs-toploader/pages';

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