next-nprogress-bar

v2.4.2

Published

7 days ago

NextJS progress bar compatible with new app directory

Downloads

283,143

0High
0Medium
0Low

skyleen

next nextjs next js react nprogress progress bar progress bar app directory

Now using NProgress V2 🚀

Getting started

Install

npm install next-nprogress-bar

yarn add next-nprogress-bar

Import

Import it into your /pages/_app(.js/.jsx/.ts/.tsx) or /app/layout(.js/.jsx/.ts/.tsx) folder

// In app directory
import { AppProgressBar as ProgressBar } from 'next-nprogress-bar';

// In pages directory
import { PagesProgressBar as ProgressBar } from 'next-nprogress-bar';

Use

<ProgressBar />

Example with /pages/_app

JavaScript

import { PagesProgressBar as ProgressBar } from 'next-nprogress-bar';

export default function App({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <ProgressBar
        height="4px"
        color="#fffd00"
        options={{ showSpinner: false }}
        shallowRouting
      />
    </>
  );
}

TypeScript

import type { AppProps } from 'next/app';
import { PagesProgressBar as ProgressBar } from 'next-nprogress-bar';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <ProgressBar
        height="4px"
        color="#fffd00"
        options={{ showSpinner: false }}
        shallowRouting
      />
    </>
  );
}

Example with /app/layout

JavaScript

First approach in a use client layout

// In /app/layout.jsx
'use client';

import { AppProgressBar as ProgressBar } from 'next-nprogress-bar';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <ProgressBar
          height="4px"
          color="#fffd00"
          options={{ showSpinner: false }}
          shallowRouting
        />
      </body>
    </html>
  );
}

Second approach wrap in a use client Providers component

See Next.js documentation

/components/ProgressBarProvider.jsx

// Create a Providers component to wrap your application with all the components requiring 'use client', such as next-nprogress-bar or your different contexts...
'use client';

import { AppProgressBar as ProgressBar } from 'next-nprogress-bar';

const Providers = ({ children }) => {
  return (
    <>
      {children}
      <ProgressBar
        height="4px"
        color="#fffd00"
        options={{ showSpinner: false }}
        shallowRouting
      />
    </>
  );
};

export default Providers;

/app/layout.jsx

// Import and use it in /app/layout.jsx
import Providers from './providers';

export const metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
};

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

TypeScript

First approach in a use client layout

// In /app/layout.tsx
'use client';

import { AppProgressBar as ProgressBar } from 'next-nprogress-bar';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <ProgressBar
          height="4px"
          color="#fffd00"
          options={{ showSpinner: false }}
          shallowRouting
        />
      </body>
    </html>
  );
}

Second approach wrap in a use client Providers component

See Next.js documentation

/components/ProgressBarProvider.tsx

// Create a Providers component to wrap your application with all the components requiring 'use client', such as next-nprogress-bar or your different contexts...
'use client';

import { AppProgressBar as ProgressBar } from 'next-nprogress-bar';

const Providers = ({ children }: { children: React.ReactNode }) => {
  return (
    <>
      {children}
      <ProgressBar
        height="4px"
        color="#fffd00"
        options={{ showSpinner: false }}
        shallowRouting
      />
    </>
  );
};

export default Providers;

/app/layout.tsx

// Import and use it in /app/layout.tsx
import Providers from './providers';

export const metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Data attributes

Disable progress bar on specific links

You can disable the progress bar on specific links by adding the data-disable-nprogress={true} attribute.

/!\ This will not work for Link in svg elements.

<Link href="#features" data-disable-nprogress={true}>
  Features
</Link>

Prevent progress

You can prevent the progress bar from starting by adding the data-prevent-nprogress={true} attribute.

<Link href="/dashboard">
  <span>Dashboard</span>
  <span onClick={(e) => e.preventDefault()} data-prevent-nprogress={true}>
    preventDefault
  </span>
</Link>

Props

height optional - string

Height of the progress bar - by default 2px

color optional - string

Color of the progress bar - by default #0A2FFF

options optional - NProgressOptions

by default undefined

See NProgress V2 docs

spinnerPosition optional - SpinnerPosition ('top-left' | 'top-right' | 'bottom-left' | 'bottom-right')

Position of the spinner (if showSpinner is true) - by default top-right

shallowRouting optional - boolean

Do not display the progress bar when the query parameters change but the route remains the same - by default false

See Next.js docs

startPosition optional - number

The position the progress bar starts at from 0 to 1 - by default 0

delay optional - number

When the page loads faster than the progress bar, it does not display - by default 0

disableSameURL optional - boolen

Disable the progress bar when the target URL is the same as the current URL - by default true

stopDelay optional - number

The delay in milliseconds before the progress bar stops - by default 0

nonce optional - string

A cryptographic nonce (number used once) used to declare inline scripts for Content Security Policy - by default undefined

memo optional - boolean

A cryptographic nonce (number used once) used to declare inline scripts for Content Security Policy - by default true

style optional - string

Your custom CSS - by default NProgress CSS

shouldCompareComplexProps optional - boolean

Activates a detailed comparison of component props to determine if a rerender is necessary. When true, the component will only rerender if there are changes in key props such as color, height, shallowRouting, delay, options, and style. This is useful for optimizing performance in scenarios where these props change infrequently. If not provided or set to false, the component will assume props have not changed and will not rerender, which can enhance performance in scenarios where the props remain static. - by default undefined

targetPreprocessor optional - (url: URL) => URL - (only for app directory progress bar)

Provides a custom function to preprocess the target URL before comparing it with the current URL. This is particularly useful in scenarios where URLs undergo transformations, such as localization or path modifications, after navigation. The function takes a URL object as input and should return a modified URL object. If this prop is provided, the preprocessed URL will be used for comparisons, ensuring accurate determination of whether the navigation target is equivalent to the current URL. This can prevent unnecessary display of the progress bar when the target URL is effectively the same as the current URL after preprocessing. - by default undefined

App directory router

Import

import { useRouter } from 'next-nprogress-bar';

Types

router.push(url: string, options?: NavigateOptions, NProgressOptions?: RouterNProgressOptions)
router.replace(url: string, options?: NavigateOptions, NProgressOptions?: RouterNProgressOptions)
router.back(NProgressOptions?: RouterNProgressOptions)

NavigateOptions is the options of the next router.

interface RouterNProgressOptions {
  showProgressBar?: boolean;
  startPosition?: number;
  disableSameURL?: boolean;
}

Use

Replace your 'next/navigation' routers with this one. It's the same router, but this one supports NProgress.

const router = useRouter();

// With progress bar
router.push('/about');
router.replace('/?counter=10');
router.back();

It also has an optional parameter (customRouter) that allows you to use this router with another custom router (for example, it could be the one from next-intl):

import { useRouter as useAnotherCustomRouter } from 'sample-package';
const router = useRouter(useAnotherCustomRouter);

// With progress bar
router.push('/about');
router.replace('/?counter=10');
router.back();

Migrating from v1 to v2

Pages directory

// before (v1)
import ProgressBar from 'next-nprogress-bar';

<ProgressBar
  height="4px"
  color="#fffd00"
  options={{ showSpinner: false }}
  shallowRouting
/>;

// after (v2)
import { PagesProgressBar as ProgressBar } from 'next-nprogress-bar';

<ProgressBar
  height="4px"
  color="#fffd00"
  options={{ showSpinner: false }}
  shallowRouting
/>;

App directory

// before (v1)
import ProgressBar from 'next-nprogress-bar';

<ProgressBar
  height="4px"
  color="#fffd00"
  options={{ showSpinner: false }}
  appDirectory
  shallowRouting
/>;

// after (v2)
import { AppProgressBar as ProgressBar } from 'next-nprogress-bar';

<ProgressBar
  height="4px"
  color="#fffd00"
  options={{ showSpinner: false }}
  shallowRouting
/>;

Issues

I am no longer upgrading this package. If you encounter any problems, do not hesitate to make a PR here.

LICENSE

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Table of Contents

Getting started

Install

Import

Use

Example with /pages/_app

JavaScript

TypeScript

Example with /app/layout

JavaScript

First approach in a use client layout

Second approach wrap in a use client Providers component

/components/ProgressBarProvider.jsx

/app/layout.jsx

TypeScript

First approach in a use client layout

Second approach wrap in a use client Providers component

/components/ProgressBarProvider.tsx

/app/layout.tsx

Data attributes

Disable progress bar on specific links

Prevent progress

Props

height optional - string

color optional - string

options optional - NProgressOptions

spinnerPosition optional - SpinnerPosition ('top-left' | 'top-right' | 'bottom-left' | 'bottom-right')

shallowRouting optional - boolean

startPosition optional - number

delay optional - number

disableSameURL optional - boolen

stopDelay optional - number

nonce optional - string

memo optional - boolean

style optional - string

shouldCompareComplexProps optional - boolean

targetPreprocessor optional - (url: URL) => URL - (only for app directory progress bar)

App directory router

Import

Types

Use

Migrating from v1 to v2

Pages directory

App directory

Issues

LICENSE