A Next.js npm package that adds a top scroll progress bar to your Next.js apps, compatible with both Pages Router and App Router.
npm install nextjs-top-scroll-progress-barA lightweight Next.js component that adds a customizable scroll progress bar at the top of your page. The progress bar indicates how far the user has scrolled through the content, providing a better user experience.
- Automatic scroll progress tracking
- Customizable appearance (height and color)
- Works with Next.js App Router
- Zero dependencies
- TypeScript support
See CHANGELOG.md for release history and updates.
``bash`
npm install nextjs-top-scroll-progress-baror
yarn add nextjs-top-scroll-progress-baror
pnpm add nextjs-top-scroll-progress-bar
The component can be used with both the App Router (Next.js 13+) and the Pages Router. Choose the appropriate setup based on your project.
1. Create a client component for the progress bar (since it uses browser APIs):
`tsx
// app/components/ClientTopScrollProgressBar.tsx
'use client'
import { TopScrollProgressBar } from 'nextjs-top-scroll-progress-bar'
interface TopScrollProgressBarProps {
height?: number;
color?: string;
}
export default function ClientTopScrollProgressBar({ height, color }: TopScrollProgressBarProps) {
return
}
`
2. Use the component in your root layout:
`tsx
// app/layout.tsx
import ClientTopScrollProgressBar from './components/ClientTopScrollProgressBar'
export default function RootLayout({ children }) {
return (
$3
1. Create a client component for the progress bar:
`tsx
// components/ClientTopScrollProgressBar.tsx
import { TopScrollProgressBar } from 'nextjs-top-scroll-progress-bar'interface TopScrollProgressBarProps {
height?: number;
color?: string;
}
export default function ClientTopScrollProgressBar({ height, color }: TopScrollProgressBarProps) {
return
}
`2. Add it to your
_app.tsx:`tsx
// pages/_app.tsx
import type { AppProps } from 'next/app'
import ClientTopScrollProgressBar from '../components/ClientTopScrollProgressBar'export default function App({ Component, pageProps }: AppProps) {
return (
<>
>
)
}
`Props
The component accepts the following props:
| Prop | Type | Default | Description |
|------|------|---------|-------------|
|
color | string | '#FF0000' | Color of the progress bar. Accepts any valid CSS color value (hex, rgb, hsl, etc.) |
| height | number | 4 | Height of the progress bar in pixels |Examples
`tsx
// Default appearance
// Custom red color with 4px height
// Using RGB color
`Development
$3
`
├── src/ # Source code
│ ├── TopScrollProgressBar.tsx # Main component
│ └── index.ts # Entry point
├── dist/ # Built files (generated)
├── __tests__/ # Test files
└── package.json # Project configuration
`$3
1. Clone the repository:
`bash
git clone https://github.com/renjith100/nextjs-top-scroll-progress-bar.git
cd nextjs-top-scroll-progress-bar
`2. Install dependencies:
`bash
npm install
`3. Start development:
`bash
npm run build # Build the package
`$3
To test the package locally before publishing:
1. In your package directory, create a local package:
`bash
npm pack
`
This will create a file like nextjs-top-scroll-progress-bar-0.0.2.tgz2. In your Next.js project's
package.json, add the local package:
`json
{
"dependencies": {
"nextjs-top-scroll-progress-bar": "file:/path/to/nextjs-top-scroll-progress-bar-0.0.2.tgz"
}
}
`3. Install the package in your Next.js project:
`bash
npm install
`4. Use the component as described in the Usage section above.
Whenever you make changes to the package:
1. Rebuild the package:
npm run build
2. Create a new package: npm pack
3. Reinstall in your Next.js project: npm install$3
The project uses Jest and React Testing Library for testing. Tests are located in the
src/__tests__ directory.`bash
Run tests once
npm testRun tests in watch mode (for development)
npm run test:watch
`The test suite includes:
- Component rendering tests
- Props validation tests
- Scroll behavior tests
$3
The package uses Rollup for building and generates both ESM and CommonJS formats:
`bash
npm run build
`This will create:
-
dist/index.cjs.js - CommonJS format
- dist/index.esm.js - ES Module format
- dist/index.d.ts` - TypeScript declarationsMIT