progressbar

Tiny, framework-agnostic progress bar for browser apps. Great for route transitions, async actions, and "loading" UX.

Install

npm i @elliotanderson43/progressbar
# or
pnpm add @elliotanderson43/progressbar
# or
yarn add @elliotanderson43/progressbar

Quick Start

import { createProgressBar } from "@elliotanderson43/progressbar";

const bar = createProgressBar({
    color: "#29d",
    height: 3,
    position: "top", // "top" | "bottom"
    minDurationMs: 250, // prevents "flash" on fast operations
});

bar.start();
setTimeout(() => bar.done(), 1200);

Track promises (ref-counted)

track() keeps the bar visible until all tracked operations finish.

import { createProgressBar } from "@elliotanderson43/progressbar";

const bar = createProgressBar();

const a = bar.track(fetch("/api/a"));
const b = bar.track(fetch("/api/b"));

await Promise.all([a, b]); // bar finishes after both complete

You can also override the minimum duration per operation:

await bar.track(fetch("/api/fast"), { minDurationMs: 400});

Determinate Progress

For real progress (0 to 1):

const bar = createProgressBar();

bar.start();
bar.set(0.25);
bar.set(0.5);
bar.set(0.9);
bar.done();

Update UI at runtime

const bar = createProgressBar();

bar.setPosition("bottom");
bar.setColor("#10b981"); // green
// or:
bar.configure({ color: "#e11d48", height: 4 });

API

• createProgressBar(options?)
• bar.start()
• bar.set(progress: number)
• bar.inc(amount?: number)
• bar.done(force?: boolean)
• bar.wrap(fn: () => Promise<T>): Promise<T>
• bar.track(promise: Promise<T>, opts?): Promise<T>
• bar.setPosition("top" | "bottom")
• bar.setColor(color: string)
• bar.configure(options)
• bar.destroy()

License

MIT