Next.js App Router demo and package docs

Show route progress with a CSP-safe bar built for Next.js App Router and React.

Use @vctqs1/nav-progress-bar-react in Next.js App Router for the simplest setup. Use @vctqs1/nav-progress-bar directly when you want the browser Navigation API wiring in a plain React app or vanilla page.

Quick startConfigurationTry the demo

Live demo

The bar starts on navigation, advances while the route is loading, and fades out on completion.

Quick start

React / Next.js App Router

Recommended for Next.js App Router. The wrapper renders the element and keeps the transition hook in your app layer.

pnpm add @vctqs1/nav-progress-bar-react
import NavProgressBar from '@vctqs1/nav-progress-bar-react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <NavProgressBar primary="#3fffa8" height="3px" />
        {children}
      </body>
    </html>
  );
}

start() belongs in instrumentation-client.ts or your own transition hook for Next.js App Router.

import {
  registerNavProgressBar,
  getNavProgressBar,
} from '@vctqs1/nav-progress-bar-react';

registerNavProgressBar();

export function onRouterTransitionStart(
  url: string,
  navigationType: 'push' | 'replace' | 'traverse',
) {
  console.log(`Navigation started: ${navigationType} to ${url}`);
  getNavProgressBar()?.start();
}

Core package

Use the core element when you want browser navigation events to drive the bar automatically.

pnpm add @vctqs1/nav-progress-bar
import { registerNavProgressBar, getNavProgressBar } from '@vctqs1/nav-progress-bar';

registerNavProgressBar({ primary: '#006bde', height: '3px' });

const nav = (globalThis as { navigation?: EventTarget }).navigation;
if (nav?.addEventListener) {
  nav.addEventListener('navigate', () => getNavProgressBar()?.start());
}

Navigation lifecycle

The browser Navigation API emits lifecycle events automatically. Next.js App Router requires manual control.

Why does Next.js require manual control?

The browser Navigation API emits navigate and navigatesuccess events automatically. Next.js App Router does not expose equivalent lifecycle events, so applications must call start() and finish() manually.


Browser Navigation API

Automatic
navigate
↓
Progress bar starts
↓
Page transition
↓
navigatesuccess
↓
Progress bar finishes

Next.js App Router

Manual
router.push()
↓
start() -- need call inside onRouterTransitionStart
↓
RSC / Route loading
↓
Route settles
↓
finish() -- do not call manually as it already added automatically

Configuration

Set color and height either on the element or during registration.

NameDefaultNotes
primaryvar(--token, #006bde)Pass a CSS variable token like --brand-color or #HEX to keep the bar themeable.
height3pxUse height="--token" if you want a CSS variable fallback.

Use @vctqs1/nav-progress-bar-react for App Router projects and @vctqs1/nav-progress-bar when you want the underlying web component directly.

Try the demo routes

These links trigger route transitions so you can watch the progress bar settle against real navigation.

Resources

Package links and project references live here instead of inside the demo section.

React@vctqs1/nav-progress-bar-reactInstall the wrapper for Next.js App Router.Core@vctqs1/nav-progress-barUse the underlying web component directly.GitHubSource repoView the code, issues, and release history.LinkedInThu Vo CatConnect with me on LinkedIn.

Programmatic Navigation Demo (useRouter)

Click any action below to trigger route transitions and watch the top progress bar.