@vctqs1/nav-progress-bar-react
v0.3.0
Published
Lightweight navigation progress bar for React and Next.js App Router with zero dependencies
Downloads
1,012
Maintainers
vctqs1Keywords
Readme
@vctqs1/nav-progress-bar-react
React wrapper for @vctqs1/nav-progress-bar. It renders the <vctqs1-nav-progress-bar> custom element, re-exports the core API, and adds JSX typing so React and Next.js App Router can use it without extra setup.
Live demo: https://nav-progress-bar.vercel.app/
Demo video:
Installation
pnpm add @vctqs1/nav-progress-bar-reactQuick Start
Next.js App Router
Use this wrapper when you want a React component in app/layout.tsx. The core package still wires browser navigation events in normal browser setups, but App Router should call start() from its own transition hook.
// app/layout.tsx
import NavProgressBar from '@vctqs1/nav-progress-bar-react';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<body>
<NavProgressBar primary="#3fffa8" />
{children}
</body>
</html>
);
}// instrumentation-client.ts
import { getNavProgressBar, registerNavProgressBar } from '@vctqs1/nav-progress-bar-react';
registerNavProgressBar();
export function onRouterTransitionStart() {
getNavProgressBar()?.start();
}In the demo app, product routes intentionally delay their server response so you can see the progress bar appear before the route-level loading.tsx fallback.
React SPA
In a normal React app, register once and render the wrapper. The core package wires the Navigation API listeners itself in supported browsers.
import NavProgressBar, { registerNavProgressBar } from '@vctqs1/nav-progress-bar-react';
registerNavProgressBar();
export default function App() {
return (
<>
<NavProgressBar />
<main>{/* routes */}</main>
</>
);
}Why This Package Exists
The core package is framework-agnostic. This wrapper exists to make React usage feel native:
- It renders the custom element from JSX.
- It ships JSX types so TypeScript accepts
<vctqs1-nav-progress-bar>. - It keeps SSR-friendly declarative shadow DOM support available without forcing React into the core package.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| primary | string | #006bde | Bar color. Accepts a hex color or a CSS custom property name like --brand-color. |
| height | string | 3px | Bar height. Accepts a CSS length or a CSS custom property name like --nav-bar-height. |
loading.tsx vs NavProgressBar
loading.tsx only appears after the server responds. The progress bar can start earlier, but in Next.js App Router that start signal should come from your own transition hook, not from the browser navigate event alone.
// app/products/[id]/loading.tsx
export default function Loading() {
return <p>Loading product…</p>;
}That is why the demo uses a delayed product route: the bar should show first, then the loading skeleton should take over, then the page content should render.
SSR
The wrapper renders the custom element server-side, and the underlying component reuses declarative shadow DOM during hydration. That avoids the flash you would get from mounting an empty custom element and filling it later in the browser.
Related
License
MIT