Package Exports

@jamalofficial/top-progress-bar
@jamalofficial/top-progress-bar/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@jamalofficial/top-progress-bar) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

🟦 Top Progress Bar

A lightweight, customizable top-loading progress bar for React apps. Designed to be globally accessible with the useTopBar() hook and no external dependencies. Ideal for showing loading states during async operations like route transitions, API calls, or dynamic UI rendering.

🚀 Features

🔁 Global control with useTopBar()
⏱ Continuous, step, and manual percentage modes
🎨 Customizable color, height, and animation speed
💡 Zero dependencies — pure React + CSS
🌐 SSR-friendly and easy to integrate into any React project

📦 Installation

npm install top-progress-bar
# or
pnpm add top-progress-bar
# or
yarn add top-progress-bar

🛠️ Usage

1️⃣ Wrap your app in the `TopProgressBarProvider`

// App.jsx or Layout.jsx
import { TopProgressBarProvider } from 'top-progress-bar';

function App() {
  return (
    <TopProgressBarProvider color="#1d4ed8" height="3px" speed={300}>
      <YourApp />
    </TopProgressBarProvider>
  );
}

2️⃣ Use the `useTopBar` hook anywhere

import { useTopBar } from 'top-progress-bar';

function ExampleComponent() {
  const { start, step, set, complete } = useTopBar();

  const handleLoad = async () => {
    start();                  // auto-starts at 5%, increases automatically
    await delay(1000);
    step(20);                 // add 20%
    await delay(500);
    set(80);                  // jump to 80%
    await delay(500);
    complete();               // fill to 100% then hide
  };

  return <button onClick={handleLoad}>Load Something</button>;
}

function delay(ms) {
  return new Promise((res) => setTimeout(res, ms));
}

⚙️ API

`TopProgressBarProvider` Props

Prop	Type	Default	Description
`color`	`string`	`#2563eb`	The color of the progress bar
`height`	`string`	`4px`	Height of the bar (e.g., `"3px"`, `"5px"`)
`speed`	`number`	`300`	Auto-progress speed (ms interval)

`useTopBar()` Hook

Provides access to control functions:

Method	Description
`start()`	Starts auto-incrementing progress bar
`step(n)`	Increases progress by `n` percent (e.g., `step(10)`)
`set(n)`	Sets the exact progress (e.g., `set(80)`)
`complete()`	Finishes the bar at 100%, then hides after a delay

❗ The bar is automatically hidden when complete() is called or set(100) is reached.

🧪 Example

const bar = useTopBar();

useEffect(() => {
  bar.start();

  fetchData().then(() => {
    bar.complete();
  });
}, []);

🧱 Built With

✅ React 17+ or 18+
✅ Pure CSS transitions
✅ React Context + useRef + forwardRef
❌ No third-party animation libraries

📝 License

🧑‍💻 Contributing

Contributions are welcome! Please open an issue or submit a PR.

🌐 Links

🔗 NPM: https://github.com/jamalofficial/top-progress-bar
🐙 GitHub: https://www.npmjs.com/package/@jamalofficial/top-progress-bar

@jamalofficial/top-progress-bar