TheSGJ/nextjs-toploaderPublic

NotificationsYou must be signed in to change notification settings
Fork57
Star985

A Next.js Top Loading Bar component made using nprogress, works with Next.js 15 , Next.js 14 and React.

License

MIT license

985 stars 57 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 124 Commits
.github		.github
.vscode		.vscode
.yarn		.yarn
src		src
.eslintignore		.eslintignore
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc.json		.prettierrc.json
.yarnrc.yml		.yarnrc.yml
CHANGELOG.md		CHANGELOG.md
JSR.md		JSR.md
LICENSE		LICENSE
README.md		README.md
deno.d.ts		deno.d.ts
deno.json		deno.json
deno.lock		deno.lock
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
yarn.lock		yarn.lock

Repository files navigation

Next Js TopLoader

A Next.js Top Loading Bar component made using nprogress, works with Next.js 14 and React.

Install

using npm:

npm install nextjs-toploader

using yarn:

yarn add nextjs-toploader

Usage

import using:

importNextTopLoaderfrom'nextjs-toploader';

Usage with`app/layout.js` for`app` folder structure

For rendering add<NextTopLoader /> to yourreturn() inside the<body></body> ofRootLayout():

importNextTopLoaderfrom'nextjs-toploader';exportdefaultfunctionRootLayout({ children}){return(<htmllang="en"><body><NextTopLoader/>{children}</body></html>);}

Usage with`pages/_app.js` for`pages` folder structure

For rendering add<PagesTopLoader /> to yourreturn() inMyApp() (Recommended):

import{PagesTopLoader}from'nextjs-toploader/pages';exportdefaultfunctionMyApp({ Component, pageProps}){return(<><PagesTopLoader/><Component{...pageProps}/>;</>);}

You can also use<NextTopLoader /> inpages router, but it's recommended to use<PagesTopLoader /> foruseRouter hook support fromnextjs-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 usinguseRouter hook (app router):

// Import the useRouter hook from nextjs-toploader to trigger the TopLoaderimport{useRouter}from'nextjs-toploader/app';

Then simply use it in your code for example:

constrouter=useRouter();router.push('/some-page');

`useRouter` hook usage with`pages/_app.js` for`pages` folder structure

For triggering TopLoader when usinguseRouter add<PagesTopLoader /> to yourreturn() inMyApp() :

import{PagesTopLoader}from'nextjs-toploader/pages';exportdefaultfunctionMyApp({ Component, pageProps}){return(<><PagesTopLoader/><Component{...pageProps}/>;</>);}

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

'use client';importReactfrom'react';import{useTopLoader}from'nextjs-toploader';constComponent=()=>{constloader=useTopLoader();return(<div><buttontype="button"onClick={()=>loader.start()}>        Start</button><buttontype="button"onClick={()=>loader.setProgress(0.5)}>        Set Progress</button></div>);};exportdefaultComponent;

Usage with React, Vite React or any other React Based Framework

For rendering add<NextTopLoader /> to yourreturn() inside the component inApp() in your App.js:

importNextTopLoaderfrom'nextjs-toploader';constApp=()=>{return(<div><Router><NextTopLoader/><Routes>{/* Your Routes Here */}</Routes></Router></div>);};exportdefaultApp;

Default Configuration

If no props are passed to<NextTopLoader />, below is the default configuration applied.

<NextTopLoadercolor="#2299DD"initialPosition={0.08}crawlSpeed={200}height={3}crawl={true}showSpinner={true}easing="ease"speed={200}shadow="0 0 10px #2299DD,0 0 5px #2299DD"template='<div role="bar"><div></div></div>  <div role="spinner"><div></div></div>'zIndex={1600}showAtBottom={false}/>

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 inms.
speed: animation speed for the TopLoader inms
easing: animation settings using easing (a CSS easing string).
height: height of TopLoader inpx.
crawl: auto incrementing behavior for the TopLoader.
showSpinner: to show spinner or not.
shadow: a smooth shadow for the TopLoader. (set it tofalse 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 tofalse 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`	`"<div role="bar"><div></div></div><div role="spinner"><div></div></div>"`
`zIndex`	`number`	`1600`
`showAtBottom`	`boolean`	`false`
`showForHashAnchor`	`boolean`	`true`