next-nprogress-bar
Version:
NextJS progress bar compatible with new app directory
516 lines (384 loc) • 13.3 kB
Markdown
<div align="center">
<h1>Next NProgress bar</h1>
<p>NProgress integration on Next.js compatible with /app and /pages folders</p>
<b>Next NProgress Bar and NProgress V2 become BProgress!</b>
</div>
The `next-nprogress-bar` and `nprogress-v2` packages remain available and usable in their current versions, but will no longer be maintained. We therefore advise you to migrate to [`@bprogress/next`](https://www.npmjs.com/package/@bprogress/next).
## Migration to BProgress
[Go to the migration documentation](https://bprogress.vercel.app/docs/next/migration)
## Table of Contents
- [Getting started](#getting-started)
- [Install](#install)
- [Import](#import)
- [Use](#use)
- [Example with /pages/\_app](#example-with-pagesapp)
- [JavaScript](#javascript)
- [TypeScript](#typescript)
- [Example with /app/layout](#example-with-applayout)
- [JavaScript](#javascript)
- [First approach in a use client layout](#first-approach-in-a-use-client-layout)
- [Second approach wrap in a use client Providers component](#second-approach-wrap-in-a-use-client-providers-component)
- [TypeScript](#typescript)
- [First approach in a use client layout](#first-approach-in-a-use-client-layout)
- [Second approach wrap in a use client Providers component](#second-approach-wrap-in-a-use-client-providers-component)
- [Data attributes](#data-attributes)
- [Disable progress bar on specific links](#disable-progress-bar-on-specific-links)
- [Props](#props)
- [height](#height)
- [color](#color)
- [options](#options)
- [spinnerPosition](#spinnerPosition)
- [appDirectory](#appdirectory)
- [shallowRouting](#shallowrouting)
- [startPosition](#startposition)
- [delay](#delay)
- [disableSameURL](#disableSameURL)
- [stopDelay](#stopdelay)
- [nonce](#nonce)
- [style](#style)
- [disableStyle](#disablestyle)
- [shouldCompareComplexProps](#shouldcomparecomplexprops)
- [targetPreprocessor](#targetpreprocessor)
- [startOnLoad](#startonload)
- [App directory router](#app-directory-router)
- [Import](#import)
- [Types](#types)
- [Use](#use)
- [Migrating from v1 to v2](#migrating-from-v1-to-v2)
- [Issues](#issues)
- [LICENSE](#license)
## Getting started
### Install
```bash
npm install next-nprogress-bar
```
or
```bash
yarn add next-nprogress-bar
```
### Import
_Import it into your **/pages/\_app(.js/.jsx/.ts/.tsx)** or **/app/layout(.js/.jsx/.ts/.tsx)** folder_
```javascript
// In app directory
import { AppProgressBar as ProgressBar } from 'next-nprogress-bar';
// In pages directory
import { PagesProgressBar as ProgressBar } from 'next-nprogress-bar';
```
### Use
```javascript
<ProgressBar />
```
## Example with /pages/\_app
### JavaScript
```jsx
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
```tsx
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
```jsx
// 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](https://nextjs.org/docs/getting-started/react-essentials#rendering-third-party-context-providers-in-server-components)
##### /components/ProgressBarProvider.jsx
```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
```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
```tsx
// 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](https://nextjs.org/docs/getting-started/react-essentials#rendering-third-party-context-providers-in-server-components)
##### /components/ProgressBarProvider.tsx
```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
```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._
```jsx
<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.
```jsx
<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](https://www.npmjs.com/package/nprogress-v2#configuration)
### 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](https://nextjs.org/docs/pages/building-your-application/routing/linking-and-navigating#shallow-routing)
### 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](https://github.com/Skyleen77/nprogress-v2/blob/main/src/index.css)**
### disableStyle
Disable the default CSS - **by default false**
If you need to disable the default CSS, you will need to add your own CSS to see the progress bar. You can use [NProgress CSS](https://github.com/Skyleen77/nprogress-v2/blob/main/src/index.css) as a base.
### 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**
### startOnLoad _optional_ - _boolean_
Start the progress bar on load - **by default false**
## App directory router
### Import
```jsx
import { useRouter } from 'next-nprogress-bar';
```
### Types
```tsx
router.push(url: string, options?: NavigateOptions, NProgressOptions?: RouterNProgressOptions)
router.replace(url: string, options?: NavigateOptions, NProgressOptions?: RouterNProgressOptions)
router.back(NProgressOptions?: RouterNProgressOptions)
router.refresh(NProgressOptions?: RouterNProgressOptions)
```
`NavigateOptions` is the options of the next router.
```tsx
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.
```tsx
const router = useRouter();
// With progress bar
router.push('/about');
router.replace('/?counter=10');
router.back();
router.refresh();
```
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`):
```tsx
import { useRouter as useAnotherCustomRouter } from 'sample-package';
const router = useRouter(useAnotherCustomRouter);
// With progress bar
router.push('/about');
router.replace('/?counter=10');
router.back();
router.refresh();
```
## Migrating from v1 to v2
### Pages directory
```jsx
// 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
```jsx
// 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](https://github.com/Skyleen77/next-nprogress-bar).
## LICENSE
MIT