h9ee-progressbar-next
v1.0.3
Published
A React + TypeScript progress bar provider for Next.js App Router
Maintainers
h9eeReadme
h9ee-progressbar-next
A minimal, customizable React progress bar component for Next.js App Router (v13+).
Features:
- Automatic top-loading indicator on client-side route transitions
- Configurable color and height
- Support for custom loader components
- No external dependencies (built-in simulation similar to NProgress)
Table of Contents
Installation
Install the package via npm or yarn:
npm install h9ee-progressbar-next
# or
yarn add h9ee-progressbar-nextPeer Dependencies:
- React 18.x
- Next.js >= 13.4.0 (App Router)
Ensure your project uses the Next.js App Router (i.e., has an /app directory).
Usage
Wrap your Root Layout
In your app/layout.tsx (or equivalent), import and wrap your application:
'use client'
import ProgressBarProvider from 'h9ee-progressbar-next';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<ProgressBarProvider>
{children}
</ProgressBarProvider>
</body>
</html>
);
}Default Bar
By default, the provider renders a thin, fixed-top bar:
<ProgressBarProvider>
{children}
</ProgressBarProvider>Customizing Color and Height
Adjust the color or height via props:
<ProgressBarProvider color="#0A2FFF" height="4px">
{children}
</ProgressBarProvider>Custom Bar
Supply your own loader component (e.g., spinner, animated indicator):
import ProgressBarProvider from 'h9ee-progressbar-next';
import MySpinner from './MySpinner';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<ProgressBarProvider customBar={<MySpinner />}>
{children}
</ProgressBarProvider>
</body>
</html>
);
}If you pass a JSX element (e.g.,
<MySpinner />), it will be rendered directly. PassingcustomBardisablescolorandheightprops.
API
| Prop | Type | Default | Description |
| ----------- | --------------------------------------- | --------- | ---------------------------------------------------- |
| children | React.ReactNode | — | Application UI |
| color | string | #2299DD | Bar color (ignored if customBar is set) |
| height | string | 3px | Bar height (ignored if customBar is set) |
| customBar | React.ComponentType<any> \| ReactNode | — | Custom loader component or element during navigation |
How It Works
- Client-Side Only: The provider uses
'use client'and runs in the browser. - Link Click Detection: Attaches a global click listener to capture internal
<a>clicks and triggers loading. - Route Change Detection: Uses Next.js App Router hooks (
usePathname,useSearchParams) to detect navigation completion. - Progress Simulation: Starts the bar at 10%, increments up to 90% with an interval, then jumps to 100% on completion before resetting.
- Custom Bar: Mounts your
customBarcomponent instead of the default bar when provided.
This mimics NProgress-like behavior without external dependencies.
Compatibility
- Next.js: 13.4.0, 14.x, 15.x (App Router only)
- React: 18.x
- TypeScript: v4.9+ (strict mode enabled)
Development
Clone the repository and install dependencies:
git clone https://github.com/h9ee/h9ee-progressbar-next.git
cd h9ee-progressbar-next
npm install- Build:
npm run build(compiles TS todist/and types totypes/) - Publish: Update
package.jsonversion and runnpm publish
License
This project is licensed under the MIT License. See the LICENSE file for details.