use-navigation-progress

🚀 Production-ready navigation progress hook for Next.js App Router with real progress tracking.

Features

• ✅ Real Progress Tracking - No fake simulations, tracks actual navigation steps
• ✅ Production Ready - Performance optimized with RAF, debouncing, and memory leak prevention
• ✅ TypeScript First - Fully typed with excellent IntelliSense support
• ✅ Flexible Configuration - Customizable steps, timeouts, and behaviors
• ✅ Zero Dependencies - Only requires React and Next.js (peer dependencies)

Installation

npm install use-navigation-progress
# or
yarn add use-navigation-progress
# or
pnpm add use-navigation-progress

Quick Start

'use client';
import { useNavigationProgress } from 'use-navigation-progress';

export default function NavigationBar() {
  const { status, progress } = useNavigationProgress();

  if (status !== 'loading') return null;

  return (
    <div className="fixed top-0 left-0 w-full h-1 bg-gray-200 z-50">
      <div
        className="h-full bg-blue-500 transition-all duration-200 ease-out"
        style={{ width: `${progress}%` }}
      />
    </div>
  );
}

Advanced Usage

Custom Steps & Manual Control

const progress = useNavigationProgress({
  enableAutoComplete: false, // Manual control
  timeout: 15000, // 15 second timeout
  steps: [
    { name: "route_change", weight: 20 },
    { name: "auth_check", weight: 15 },
    { name: "data_fetch", weight: 40 },
    { name: "render_complete", weight: 25 }
  ]
});

// In your component
useEffect(() => {
  checkAuth()
    .then(() => progress.markStepComplete('auth_check'))
    .then(() => fetchData())
    .then(() => progress.markStepComplete('data_fetch'))
    .finally(() => progress.finish());
}, []);

Complete Progress Bar Component

'use client';
import { useNavigationProgress } from 'use-navigation-progress';

export function ProgressBar() {
  const { status, progress, duration, error } = useNavigationProgress({
    timeout: 8000,
    debounceMs: 50
  });

  if (status === 'idle') return null;

  return (
    <div className="fixed top-0 left-0 w-full z-50">
      <div className="h-1 bg-gradient-to-r from-blue-500 to-purple-600 origin-left transform transition-transform duration-200 ease-out"
           style={{
             transform: `scaleX(${progress / 100})`,
             opacity: status === 'complete' ? 0 : 1
           }} />

      {error && (
        <div className="bg-red-500 text-white text-sm px-4 py-1">
          Navigation failed: {error}
        </div>
      )}

      {/* Optional: Show duration for debugging */}
      {process.env.NODE_ENV === 'development' && (
        <div className="text-xs text-gray-500 px-2">
          {duration}ms - {progress}%
        </div>
      )}
    </div>
  );
}

API Reference

useNavigationProgress(options?)

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | timeout | number | 10000 | Timeout in milliseconds before marking navigation as failed | | steps | Array<{name: string, weight: number}> | Default steps | Custom navigation steps with weights | | enableAutoComplete | boolean | true | Automatically complete progress when all steps are done | | debounceMs | number | 100 | Debounce time in milliseconds for progress updates |

Returns

| Property | Type | Description | |----------|------|-------------| | status | 'idle' \| 'loading' \| 'complete' \| 'error' | Current navigation status | | progress | number | Progress percentage (0-100) | | duration | number | Navigation duration in milliseconds | | error | string \| undefined | Error message if status is "error" | | finish | () => void | Manually finish the navigation progress | | markStepComplete | (stepName: string) => void | Mark a specific step as complete | | reset | () => void | Reset progress to idle state |

Default Steps

[
  { name: "route_change", weight: 20 },    // Route change detected
  { name: "component_mount", weight: 30 }, // Component mounted
  { name: "hydration", weight: 25 },       // React hydration complete
  { name: "resources_load", weight: 25 }   // Images and resources loaded
]

Styling Examples

Tailwind CSS

// Simple bar
<div className={`fixed top-0 left-0 h-1 bg-blue-500 z-50 transition-all duration-200 ${
  status === 'loading' ? 'opacity-100' : 'opacity-0'
}`} style={{ width: `${progress}%` }} />

// Gradient bar with glow
<div className="fixed top-0 left-0 w-full h-1 bg-gray-200 z-50">
  <div className="h-full bg-gradient-to-r from-blue-400 via-purple-500 to-pink-500 shadow-lg transition-all duration-300 ease-out"
       style={{ width: `${progress}%` }} />
</div>

CSS Modules

.progressBar {
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 3px;
  background: linear-gradient(90deg, #3b82f6, #8b5cf6, #ec4899);
  transform-origin: left;
  transition: transform 200ms ease-out;
  z-index: 9999;
}

.progressBar.complete {
  opacity: 0;
  transition: opacity 300ms ease-out;
}

Best Practices

1. Single Progress Bar Per App

// app/layout.tsx
import { ProgressBar } from '@/components/progress-bar';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ProgressBar />
        {children}
      </body>
    </html>
  );
}

2. Custom Loading Steps

// For data-heavy pages
const { markStepComplete } = useNavigationProgress({
  steps: [
    { name: "route_change", weight: 15 },
    { name: "auth_validation", weight: 20 },
    { name: "data_prefetch", weight: 35 },
    { name: "component_render", weight: 30 }
  ]
});

3. Error Handling

const { status, error, reset } = useNavigationProgress();

useEffect(() => {
  if (status === 'error') {
    console.error('Navigation failed:', error);
    // Optionally reset after delay
    setTimeout(reset, 3000);
  }
}, [status, error, reset]);

Demos

I've implemented a custom route announcer in slate with this package, you can implement your own top loader, custom route announcer etc with it

License

© MIT