Next NProgress bar
NProgress integration on Next.js compatible with /app and /pages folders
Table of Contents
Getting started
Install
npm install next-nprogress-bar
or
yarn add next-nprogress-bar
Import
Import it into your /pages/_app(.js/.jsx/.ts/.tsx) or /app/layout(.js/.jsx/.ts/.tsx) folder
import { AppProgressBar as ProgressBar } from 'next-nprogress-bar';
import { PagesProgressBar as ProgressBar } from 'next-nprogress-bar';
Use
<ProgressBar />
Exemple 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
/>
</>
);
}
Exemple with /app/layout
JavaScript
First approach in a use client layout
'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
'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 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
'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
'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 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>
);
}
Tips
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>
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 docs
shallowRouting optional - boolean
If the progress bar is not displayed when you only change URL parameters without changing route - 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
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;
}
Use
Replace your 'next/navigation' routers with this one. It's the same router, but this one supports NProgress.
const router = useRouter();
router.push('/about');
router.replace('/?counter=10');
router.back();
Migrating from v1 to v2
Pages directory
import ProgressBar from 'next-nprogress-bar';
<ProgressBar
height="4px"
color="#fffd00"
options={{ showSpinner: false }}
shallowRouting
/>;
import { PagesProgressBar as ProgressBar } from 'next-nprogress-bar';
<ProgressBar
height="4px"
color="#fffd00"
options={{ showSpinner: false }}
shallowRouting
/>;
App directory
import ProgressBar from 'next-nprogress-bar';
<ProgressBar
height="4px"
color="#fffd00"
options={{ showSpinner: false }}
appDirectory
shallowRouting
/>;
import { AppProgressBar as ProgressBar } from 'next-nprogress-bar';
<ProgressBar
height="4px"
color="#fffd00"
options={{ showSpinner: false }}
shallowRouting
/>;
Issues
Please file an issue for bugs, missing documentation, or unexpected behavior.
File an issue
LICENSE
MIT