https://github.com/thesgj/nextjs-toploader
A Next.js Top Loading Bar component made using nprogress, works with Next.js 15 , Next.js 14 and React.
https://github.com/thesgj/nextjs-toploader
next next13 next14 nextjs nextjs13 nextjs14 progressbar react toploader
Last synced: 1 day ago
JSON representation
A Next.js Top Loading Bar component made using nprogress, works with Next.js 15 , Next.js 14 and React.
- Host: GitHub
- URL: https://github.com/thesgj/nextjs-toploader
- Owner: TheSGJ
- License: mit
- Created: 2023-03-05T01:11:44.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2025-03-25T21:15:10.000Z (about 2 months ago)
- Last Synced: 2025-05-11T08:04:00.640Z (4 days ago)
- Topics: next, next13, next14, nextjs, nextjs13, nextjs14, progressbar, react, toploader
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/nextjs-toploader
- Size: 1.28 MB
- Stars: 1,030
- Watchers: 5
- Forks: 59
- Open Issues: 42
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# 
Next Js TopLoader
- A Next.js Top Loading Bar component made using nprogress, works with Next.js 14 and React.
[](https://www.npmjs.com/package/nextjs-toploader)
[](https://www.npmjs.com/package/nextjs-toploader)
## Install
using npm:
```bash
npm install nextjs-toploader
```
using yarn:
```bash
yarn add nextjs-toploader
```
## Usage
import using:
```js
import NextTopLoader from 'nextjs-toploader';
```
### Usage with `app/layout.js` for `app` folder structure
For rendering add `` to your `return()` inside the `` of `RootLayout()`:
```js
import NextTopLoader from 'nextjs-toploader';
export default function RootLayout({ children }) {
return (
{children}
);
}
```
### Usage with `pages/_app.js` for `pages` folder structure
For rendering add `` to your `return()` in `MyApp()` (Recommended):
```js
import { PagesTopLoader } from 'nextjs-toploader/pages';
export default function MyApp({ Component, pageProps }) {
return (
<>
;
>
);
}
```
You can also use `` in `pages` router, but it's recommended to use `` for `useRouter` hook support from `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):
```js
// Import the useRouter hook from nextjs-toploader to trigger the TopLoader
import { useRouter } from 'nextjs-toploader/app';
```
Then simply use it in your code for example:
```js
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 `` to your `return()` in `MyApp()` :
```js
import { PagesTopLoader } from 'nextjs-toploader/pages';
export default function MyApp({ Component, pageProps }) {
return (
<>
;
>
);
}
```
---
## useTopLoader Hook
A custom hook for handling progress indicators using NextTopLoader.
## Methods
| Name | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| start | Starts the progress bar |
| done | Completes the progress bar. Can be forced to complete immediately with an optional force parameter |
| remove | Removes the progress bar element from the DOM |
| setProgress | Manually sets the progress value (between 0.0 and 1.0) |
| inc | Increments the progress bar by a specified amount. If no amount is specified, it makes a small automatic increment |
| trickle | Adds small random increments to the progress bar |
| isStarted | Checks if the progress bar has been started |
| isRendered | Checks if the progress bar is rendered in the DOM |
| getPositioningCSS | Returns the positioning CSS property of the progress bar |
## Example Usage
```js
'use client';
import React from 'react';
import { useTopLoader } from 'nextjs-toploader';
const Component = () => {
const loader = useTopLoader();
return (
loader.start()}>
Start
loader.setProgress(0.5)}>
Set Progress
);
};
export default Component;
```
---
### Usage with React, Vite React or any other React Based Framework
For rendering add `` to your `return()` inside the component in `App()` in your App.js:
```js
import NextTopLoader from 'nextjs-toploader';
const App = () => {
return (
{/* Your Routes Here */}
);
};
export default App;
```
### Default Configuration
If no props are passed to ``, below is the default configuration applied.
```jsx
```
- `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 it 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)
- `showForHashAnchor`: To show for "#" url or not. (set it to `false` to disable it)
#### `NextTopLoaderProps` (props passed to the TopLoader)
| **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` | `"
"` |
| `zIndex` | `number` | `1600` |
| `showAtBottom` | `boolean` | `false` |
| `showForHashAnchor` | `boolean` | `true` |
## Contributors
### Code Contributors
This project was made possible thanks to the contributions of its code contributors.
### Financial Contribution
---
UPI ID: thesgj@upi (International UPI ID)
[](https://github.com/sponsors/TheSGJ)
[](https://www.buymeacoffee.com/thesgj)
[](https://opencollective.com/nextjs-toploader)