next-navigation-progress


A lightweight, customizable navigation progress bar for Next.js applications with React 19 support. Shows a smooth progress indicator during route transitions using React's latest features like useOptimistic and startTransition.

Demo

🚀 View Live Demo

Experience the smooth navigation progress bar in action with our interactive demo showcasing various navigation patterns and customization options.

Features

- 🚀 React 19 support with useOptimistic and startTransition
- 🎨 Fully customizable appearance
- 📦 Lightweight with zero dependencies (~2KB gzipped)
- 🔧 TypeScript support with full type definitions
- ⚡ Smooth animations with customizable easing functions
- 🎯 Easy integration with Next.js App Router
- 🔄 Automatic progress management during route transitions
- 💡 Requires 'use client' directive (uses React Context)

Installation

``bash
npm install next-navigation-progress


or

> Important: This library uses React Context and hooks, so you must add the 'use client' directive to any file that imports from next-navigation-progress.

$3

In your root layout or _app.tsx:

`tsx
'use client'; // Required! This library uses React Context

import { NextNavigationProgressProvider } from 'next-navigation-progress';

export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (



{children}



);
}
`

$3

Add the progress bar component inside the provider:

`tsx
'use client'; // Required! This library uses React Context

import {
NextNavigationProgressProvider,
NextNavigationProgressBar,
NavigationLink,
} from 'next-navigation-progress';

export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (




{children}



);
}
`

$3

You have two options for triggering the progress bar:

#### Option A: Using NavigationLink (Recommended)

The easiest way is to use the built-in NavigationLink component:

`tsx
'use client'; // Required! This library uses React Context

import { NavigationLink } from 'next-navigation-progress';

export default function MyComponent() {
return Go to About;
}
`

#### Option B: Using the hook manually

For more control, use the useNavigationProgress hook with startTransition:

`tsx
'use client'; // Required! This library uses React Context

import { useNavigationProgress } from 'next-navigation-progress';
import { useRouter } from 'next/navigation';
import { startTransition } from 'react';

export default function MyComponent() {
const router = useRouter();
const { startNewProgress } = useNavigationProgress();

const handleNavigation = (href: string) => {
startTransition(() => {
startNewProgress();
router.push(href);
});
};

return (
handleNavigation('/about')}>Go to About
);
}
`

TypeScript Examples

$3

`tsx
'use client'; // Required! This library uses React Context

import type { FC, ReactNode } from 'react';
import {
NextNavigationProgressProvider,
NextNavigationProgressBar,
NavigationLink,
} from 'next-navigation-progress';

interface LayoutProps {
children: ReactNode;
}

const RootLayout: FC = ({ children }) => {
return (






export default RootLayout;
`

$3

`tsx
'use client'; // Required! This library uses React Context

import { useNavigationProgress } from 'next-navigation-progress';
import { startTransition } from 'react';
import type { MouseEventHandler } from 'react';

function useCustomNavigation() {
const { progress, startNewProgress, optimisticObj, stateObj } =
useNavigationProgress();

const handleClick: MouseEventHandler = (e) => {
e.preventDefault();
startTransition(() => {
startNewProgress();
// Your navigation logic here
});
};

return {
progress,
isLoading: optimisticObj.loading,
isShowing: stateObj.showing,
handleClick,
};
}
`

API Reference

$3

#### NextNavigationProgressProvider

The context provider that manages the progress state.

`tsx
{children}
`

#### NextNavigationProgressBar

The progress bar component that displays the navigation progress.

`tsx

`

Currently, the progress bar uses default styling with a blue color (#228be6) and 3px height. Custom styling can be achieved by creating your own progress component using the useNavigationProgress hook.

#### NavigationLink

A pre-configured Link component that automatically triggers the progress bar:

`tsx

About Page

`

Props:

| Prop | Type | Default | Description |
| ----------- | --------------------- | ------- | ------------------------- |
| href | string | - | The destination URL |
| children | React.ReactNode | - | Link content |
| className | string | - | CSS class name |
| style | React.CSSProperties | - | Inline styles |
| target | string | - | Link target attribute |
| prefetch | boolean | - | Next.js prefetch behavior |
| onClick | function | - | Click handler |

$3

#### useNavigationProgress()

Returns the progress context with the following:

`tsx
const {
progress, // Current progress value (0-100)
startNewProgress, // Function to start new progress
optimisticObj, // { loading: boolean }
stateObj, // { showing: boolean }
} = useNavigationProgress();
`

Advanced Usage

$3

You can create your own progress component using the useNavigationProgress hook:

`tsx
'use client'; // Required! This library uses React Context

import { useNavigationProgress } from 'next-navigation-progress';

function CustomProgressBar() {
const { progress, stateObj } = useNavigationProgress();

if (!stateObj.showing) return null;

return (