A 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.
npm install nextjs-top-scroll-progress-bar
# or
yarn add nextjs-top-scroll-progress-bar
# or
pnpm add nextjs-top-scroll-progress-barThe component can be used with both the App Router (Next.js 13+) and the Pages Router. Choose the appropriate setup based on your project.
// app/layout.tsx
import { TopScrollProgressBar } from 'nextjs-top-scroll-progress-bar';
export default function RootLayout({ children }) {
return (
<html>
<body>
<TopScrollProgressBar color='#F00' height={4} />
{children}
</body>
</html>
);
}// pages/_app.tsx
import type { AppProps } from 'next/app';
import { TopScrollProgressBar } from 'nextjs-top-scroll-progress-bar';
export default function App({ Component, pageProps }: AppProps) {
return (
<>
<TopScrollProgressBar color='#F00' height={4} />
<Component {...pageProps} />
</>
);
}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 |
// Default appearance
<TopScrollProgressBar />
// Custom red color with 4px height
<TopScrollProgressBar color="#FF0000" height={4} />
// Using RGB color
<TopScrollProgressBar color="rgb(0, 128, 255)" height={3} />├── src/ # Source code
│ ├── TopScrollProgressBar.tsx # Main component
│ └── index.ts # Entry point
├── dist/ # Built files (generated)
├── __tests__/ # Test files
└── package.json # Project configuration
- Clone the repository:
git clone https://github.com/renjith100/nextjs-top-scroll-progress-bar.git
cd nextjs-top-scroll-progress-bar- Install dependencies:
npm install- Start development:
npm run build # Build the packageTo test the package locally before publishing:
- In your package directory, create a local package:
npm packThis will create a file like nextjs-top-scroll-progress-bar-x.x.x.tgz
- In your Next.js project's
package.json, add the local package:
{
"dependencies": {
"nextjs-top-scroll-progress-bar": "file:/path/to/nextjs-top-scroll-progress-bar-x.x.x.tgz"
}
}- Install the package in your Next.js project:
npm install- Use the component as described in the Usage section above.
Whenever you make changes to the package:
- Rebuild the package:
npm run build - Create a new package:
npm pack - Reinstall in your Next.js project:
npm install
The project uses Jest and React Testing Library for testing. Tests are located in the src/__tests__ directory.
# Run tests once
npm test
# Run tests in watch mode (for development)
npm run test:watchThe test suite includes:
- Component rendering tests
- Props validation tests
- Scroll behavior tests
The package uses Rollup for building and generates both ESM and CommonJS formats:
npm run buildThis will create:
dist/index.cjs.js- CommonJS formatdist/index.esm.js- ES Module formatdist/index.d.ts- TypeScript declarations
MIT