react-top-progress 0.1.1 → 1.0.1

package/README.md

@@ -1,22 +1,19 @@
 # react-top-progress
 
-![Demo of react-top-progress](demo_react_top_progress.png)
+**<a href="https://react-test-progress.vercel.app/" target="_blank">👉 View Live Demo</a>**
 
-**[👉 View Live Demo](https://react-test-progress.vercel.app/)**
+A lightweight, modern, and performant top loading progress bar for React. Built for seamless user experiences with zero dependencies!
 
-A lightweight, modern, and performant top loading progress bar for React.
-
-Perfect for Next.js App Router, Vite, and standard single-page applications.
+Perfect for Next.js App Router, Vite, and standard SPA architectures.
 
 ## Features
 
-- **0 dependencies**: Tiny footprint (~1kb gzipped).
-- **Realistic loading feel**: Increments incrementally like real network requests.
-- **Premium DX**: Controlled programmatically with simple `startProgress` / `finishProgress` API.
-- **Gradient & Glow Support**: Fully customizable colors, shadow pegs, and effects.
-- **Performant**: Uses `transform` hardware acceleration and `cubic-bezier` transitions.
+- **0 Dependencies**: Tiny footprint (~1.8kb gzipped).
+- **Advanced Loaders**: `continuous` and `static` start modes matching network logic.
+- **Premium DX**: Controlled programmatically with simple global API hooks, or direct React `ref`.
+- **Customizable**: Add gradients, background container colors, custom CSS classes, and glows.
+- **Performant**: Uses `transform: translateZ(0)` hardware acceleration and `cubic-bezier` CSS transitions.
 - **TypeScript ready**: Full types included.
-- **React 18+ & Next.js ready**: Contains `"use client"` where necessary.
 
 ## Installation
 
@@ -34,9 +31,7 @@ bun add react-top-progress
 
 ## Quick Start
 
-### 1. Add the component to your root layout/app
-
-At the top level of your application (like Next.js `app/layout.tsx` or Vite `src/App.tsx`), render the `<TopProgress />` component.
+At the top level of your application (like Next.js `app/layout.tsx` or Vite `src/App.tsx`), render the component.
 
 ```tsx
 import { TopProgress } from "react-top-progress";
@@ -53,52 +48,71 @@ export default function RootLayout({ children }) {
 }
 ```
 
-### 2. Control it programmatically
+## Built-in Methods
 
-Import the API from anywhere in your app to trigger the progress bar manually!
+You can trigger the loader from anywhere in your codebase by importing the functions globally, or via a React `ref` assigned to `<TopProgress ref={myRef} />`.
 
-```tsx
-import { startProgress, finishProgress } from "react-top-progress";
+| Method                                          | Parameters                 | Description                                                                                                          |
+| ----------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `start(loaderType?)`                            | `"continuous" \| "static"` | Starts the loading indicator. Default is continuous.                                                                 |
+| `continuousStart(startingValue?, refreshRate?)` | `number`, `number`         | Starts with a random value (20-30), then slowly ticks up (2-10) repetitively. Reaches max 90%.                       |
+| `staticStart(startingValue?)`                   | `number`                   | Starts the loader with a random static value between 30-50, waiting for completion.                                  |
+| `complete()` / `finishProgress()`               |                            | Instantly pushes the indicator to 100% and gracefully fades it out.                                                  |
+| `increase(value)`                               | `number`                   | Manually increments the loader by a specific amount.                                                                 |
+| `decrease(value)`                               | `number`                   | Manually decrements the loader by a specific amount.                                                                 |
+| `setProgress(value)`                            | `number`                   | Hardsets to a specific progress percentage.                                                                          |
+| `getProgress()`                                 |                            | Returns the current progress percentage (0 - 100).                                                                   |
+| `withProgress(promise)`                         | `Promise<T>`               | Wraps an asynchronous action. `startProgress()` executes automatically before and completes automatically afterward. |
 
-async function handleAction() {
-  startProgress();
+### Global Usage Example
+
+```tsx
+import {
+  startProgress,
+  finishProgress,
+  withProgress,
+} from "react-top-progress";
+
+async function fetchData() {
+  startProgress("continuous");
   try {
-    await someHeavyTask();
+    await apiCall();
   } finally {
-    finishProgress();
+    finishProgress(); // alias of complete()
   }
 }
-```
 
-### 3. The `withProgress` Utility
-
-For an even better Developer Experience, simply wrap your promises securely with `withProgress`!
-
-```tsx
-import { withProgress } from "react-top-progress";
-
-async function handleFetch() {
-  const data = await withProgress(fetch("/api/data"));
-  console.log(data);
-}
+// Or functionally wrap promises for ultimate DX:
+const loadProfile = () => withProgress(fetch("/api/profile"));
 ```
 
-## Customization API
+## Component Properties
 
-The `TopProgress` component accepts the following props:
+You can customize `<TopProgress />` passing any of the following props:
 
-| Prop        | Type      | Default     | Description                                                                                                  |
-| ----------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
-| `color`     | `string`  | `"#29D"`    | Flat hex color or `linear-gradient(...)` function string                                                     |
-| `height`    | `number`  | `3`         | Height of the progress bar in pixels                                                                         |
-| `showGlow`  | `boolean` | `true`      | Whether to display the premium box-shadow drop-glow and trailing peg                                         |
-| `glowColor` | `string`  | `undefined` | Optionally override the color of the glow effect. By default, it infers realistically from your main `color` |
-| `zIndex`    | `number`  | `9999`      | The z-index stacking context level.                                                                          |
+| Property             | Type            | Default         | Description                                                                                       |
+| -------------------- | --------------- | --------------- | ------------------------------------------------------------------------------------------------- |
+| `progress`           | `number`        |                 | Hardset the progress (0-100) if you want to bypass the internal store and control state yourself. |
+| `color`              | `string`        | `"red"`         | Background color of the bar. Accepts `linear-gradient(...)` or hex codes.                         |
+| `height`             | `number`        | `2`             | Height of the progress bar in pixels.                                                             |
+| `shadow`             | `boolean`       | `true`          | Appends a glorious trailing drop-glow peg matching the bar's color tracking its head.             |
+| `background`         | `string`        | `"transparent"` | Fills the container div's background layer under the progress element.                            |
+| `transitionTime`     | `number`        | `300`           | Fade transition time (ms) for the fade-out completion sequence.                                   |
+| `loaderSpeed`        | `number`        | `500`           | Loader width transition speed (ms).                                                               |
+| `waitingTime`        | `number`        | `1000`          | The delay time (ms) loader waits at 100% width before fading entirely out.                        |
+| `style`              | `CSSProperties` |                 | Inject custom JSX styles directly onto the loader element.                                        |
+| `className`          | `string`        |                 | Apply a specific custom CSS class to the loader element.                                          |
+| `containerStyle`     | `CSSProperties` |                 | Configure inline styles for the fixed `<div />` wrapper container.                                |
+| `containerClassName` | `string`        |                 | Custom CSS class applied onto the wrapper container.                                              |
+| `onLoaderFinished`   | `() => void`    |                 | A callback function executing precisely when the loader fully hits 100% max width.                |
 
-## Credits & Inspiration
+## Credits
 
 Designed for the modern web. Inspired by the classic `nprogress` and Next.js' `nextjs-toploader`. Ideal when you need explicit control without relying solely on framework routing events.
 
+Built with ❤️ by **[Harry Mate](https://github.com/harrymate22)**.
+🌟 If you find this library helpful, consider dropping a **Star** on GitHub and **[following me (@harrymate22)](https://github.com/harrymate22)** for more open-source tools!
+
 ## License
 
-MIT
+MIT © [harrymate22](https://github.com/harrymate22)

package/dist/index.d.mts

@@ -1,16 +1,45 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { CSSProperties } from 'react';
 
 interface TopProgressProps {
+    progress?: number;
     color?: string;
+    shadow?: boolean;
     height?: number;
+    background?: string;
+    style?: CSSProperties;
+    containerStyle?: CSSProperties;
+    shadowStyle?: CSSProperties;
+    transitionTime?: number;
+    loaderSpeed?: number;
+    waitingTime?: number;
+    className?: string;
+    containerClassName?: string;
+    onLoaderFinished?: () => void;
     showGlow?: boolean;
     glowColor?: string;
     zIndex?: number;
 }
-declare const TopProgress: ({ color, height, showGlow, glowColor, zIndex, }: TopProgressProps) => react_jsx_runtime.JSX.Element | null;
+interface TopProgressRef {
+    start: (loaderType?: "continuous" | "static") => void;
+    continuousStart: (startingValue?: number, refreshRate?: number) => void;
+    staticStart: (startingValue?: number) => void;
+    complete: () => void;
+    increase: (value: number) => void;
+    decrease: (value: number) => void;
+    getProgress: () => number | null;
+    set: (value: number) => void;
+}
+declare const TopProgress: React.ForwardRefExoticComponent<TopProgressProps & React.RefAttributes<TopProgressRef>>;
 
-declare const startProgress: () => void;
+declare const startProgress: (type?: "continuous" | "static") => void;
+declare const continuousStart: (startingValue?: number, refreshRate?: number) => void;
+declare const staticStart: (startingValue?: number) => void;
 declare const finishProgress: () => void;
+declare const completeProgress: () => void;
+declare const increaseProgress: (value: number) => void;
+declare const decreaseProgress: (value: number) => void;
+declare const getProgress: () => number | null;
+declare const setProgress: (value: number) => void;
 declare const withProgress: <T>(promise: Promise<T>) => Promise<T>;
 
-export { TopProgress, finishProgress, startProgress, withProgress };
+export { TopProgress, type TopProgressProps, type TopProgressRef, completeProgress, continuousStart, decreaseProgress, finishProgress, getProgress, increaseProgress, setProgress, startProgress, staticStart, withProgress };

package/dist/index.d.ts

@@ -1,16 +1,45 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { CSSProperties } from 'react';
 
 interface TopProgressProps {
+    progress?: number;
     color?: string;
+    shadow?: boolean;
     height?: number;
+    background?: string;
+    style?: CSSProperties;
+    containerStyle?: CSSProperties;
+    shadowStyle?: CSSProperties;
+    transitionTime?: number;
+    loaderSpeed?: number;
+    waitingTime?: number;
+    className?: string;
+    containerClassName?: string;
+    onLoaderFinished?: () => void;
     showGlow?: boolean;
     glowColor?: string;
     zIndex?: number;
 }
-declare const TopProgress: ({ color, height, showGlow, glowColor, zIndex, }: TopProgressProps) => react_jsx_runtime.JSX.Element | null;
+interface TopProgressRef {
+    start: (loaderType?: "continuous" | "static") => void;
+    continuousStart: (startingValue?: number, refreshRate?: number) => void;
+    staticStart: (startingValue?: number) => void;
+    complete: () => void;
+    increase: (value: number) => void;
+    decrease: (value: number) => void;
+    getProgress: () => number | null;
+    set: (value: number) => void;
+}
+declare const TopProgress: React.ForwardRefExoticComponent<TopProgressProps & React.RefAttributes<TopProgressRef>>;
 
-declare const startProgress: () => void;
+declare const startProgress: (type?: "continuous" | "static") => void;
+declare const continuousStart: (startingValue?: number, refreshRate?: number) => void;
+declare const staticStart: (startingValue?: number) => void;
 declare const finishProgress: () => void;
+declare const completeProgress: () => void;
+declare const increaseProgress: (value: number) => void;
+declare const decreaseProgress: (value: number) => void;
+declare const getProgress: () => number | null;
+declare const setProgress: (value: number) => void;
 declare const withProgress: <T>(promise: Promise<T>) => Promise<T>;
 
-export { TopProgress, finishProgress, startProgress, withProgress };
+export { TopProgress, type TopProgressProps, type TopProgressRef, completeProgress, continuousStart, decreaseProgress, finishProgress, getProgress, increaseProgress, setProgress, startProgress, staticStart, withProgress };

package/dist/index.js

@@ -22,8 +22,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   TopProgress: () => TopProgress,
+  completeProgress: () => completeProgress,
+  continuousStart: () => continuousStart,
+  decreaseProgress: () => decreaseProgress,
   finishProgress: () => finishProgress,
+  getProgress: () => getProgress,
+  increaseProgress: () => increaseProgress,
+  setProgress: () => setProgress,
   startProgress: () => startProgress,
+  staticStart: () => staticStart,
   withProgress: () => withProgress
 });
 module.exports = __toCommonJS(index_exports);
@@ -37,6 +44,11 @@ var ProgressStore = class {
   value = null;
   interval = null;
   hideTimer = null;
+  config = {
+    transitionTime: 300,
+    loaderSpeed: 500,
+    waitingTime: 1e3
+  };
   subscribe(listener) {
     this.listeners.add(listener);
     listener(this.value);
@@ -47,27 +59,63 @@ var ProgressStore = class {
   notify() {
     this.listeners.forEach((listener) => listener(this.value));
   }
-  start() {
-    if (this.value !== null) return;
+  start(loaderType = "continuous") {
+    if (loaderType === "static") {
+      this.staticStart();
+    } else {
+      this.continuousStart();
+    }
+  }
+  continuousStart(startingValue, refreshRate) {
     this.cleanup();
-    this.value = 10;
+    this.value = startingValue !== void 0 ? startingValue : Math.floor(Math.random() * 10) + 20;
     this.notify();
     this.interval = setInterval(() => {
-      if (this.value !== null) {
-        const amount = Math.max(0.5, (95 - this.value) / 10);
-        this.value = Math.min(this.value + amount, 95);
+      if (this.value !== null && this.value < 90) {
+        const inc = Math.floor(Math.random() * 8) + 2;
+        this.value = Math.min(this.value + inc, 90);
         this.notify();
       }
-    }, 200);
+    }, refreshRate || this.config.loaderSpeed);
+  }
+  staticStart(startingValue) {
+    this.cleanup();
+    this.value = startingValue !== void 0 ? startingValue : Math.floor(Math.random() * 20) + 30;
+    this.notify();
+  }
+  complete() {
+    this.finish();
   }
   finish() {
     this.cleanup();
+    if (this.value === null) return;
     this.value = 100;
     this.notify();
     this.hideTimer = setTimeout(() => {
       this.value = null;
       this.notify();
-    }, 400);
+    }, this.config.waitingTime);
+  }
+  set(value) {
+    this.cleanup();
+    this.value = value;
+    this.notify();
+    if (value >= 100) {
+      this.finish();
+    }
+  }
+  increase(amount) {
+    if (this.value !== null) {
+      this.value = Math.min(this.value + amount, 100);
+      this.notify();
+      if (this.value === 100) this.finish();
+    }
+  }
+  decrease(amount) {
+    if (this.value !== null) {
+      this.value = Math.max(0, this.value - amount);
+      this.notify();
+    }
   }
   cleanup() {
     if (this.interval) clearInterval(this.interval);
@@ -76,11 +124,21 @@ var ProgressStore = class {
   getValue() {
     return this.value;
   }
+  getProgress() {
+    return this.value;
+  }
 };
 var progressStore = new ProgressStore();
 var useProgressStore = () => progressStore;
-var startProgress = () => progressStore.start();
+var startProgress = (type) => progressStore.start(type);
+var continuousStart = (startingValue, refreshRate) => progressStore.continuousStart(startingValue, refreshRate);
+var staticStart = (startingValue) => progressStore.staticStart(startingValue);
 var finishProgress = () => progressStore.finish();
+var completeProgress = () => progressStore.complete();
+var increaseProgress = (value) => progressStore.increase(value);
+var decreaseProgress = (value) => progressStore.decrease(value);
+var getProgress = () => progressStore.getProgress();
+var setProgress = (value) => progressStore.set(value);
 var withProgress = async (promise) => {
   startProgress();
   try {
@@ -95,69 +153,124 @@ var withProgress = async (promise) => {
 
 // src/TopProgress.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
-var TopProgress = ({
-  color = "#29D",
-  // Still the default flat color, but can now accept "linear-gradient(...)"
-  height = 3,
-  showGlow = true,
-  glowColor,
-  zIndex = 9999
-}) => {
-  const store = useProgressStore();
-  const [progress, setProgress] = (0, import_react.useState)(store.getValue());
-  (0, import_react.useEffect)(() => {
-    return store.subscribe(setProgress);
-  }, [store]);
-  if (progress === null) {
-    return null;
-  }
-  const isGradient = color.includes("gradient(");
-  const backgroundStyle = isGradient ? { backgroundImage: color } : { backgroundColor: color };
-  const computedGlowColor = glowColor || (isGradient ? "rgba(41, 216, 255, 0.4)" : color);
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-    "div",
-    {
-      style: {
-        position: "fixed",
-        top: 0,
-        left: 0,
-        width: `${progress}%`,
-        height: `${height}px`,
-        ...backgroundStyle,
-        // Box shadow generates a beautiful diffused glow underneath the progress bar
-        boxShadow: showGlow ? `0 0 10px ${computedGlowColor}, 0 0 5px ${computedGlowColor}` : "none",
-        // Smooth and performant 60fps CSS transitions
-        transition: "width 0.2s cubic-bezier(0.4, 0, 0.2, 1), opacity 0.4s ease",
-        opacity: progress === 100 ? 0 : 1,
-        zIndex,
-        // Force hardware acceleration for paint performance
-        transform: "translateZ(0)",
-        // Don't intercept clicks
-        pointerEvents: "none"
-      },
-      children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-        "div",
-        {
-          style: {
-            display: showGlow ? "block" : "none",
-            position: "absolute",
-            right: 0,
-            top: 0,
-            width: 100,
-            height: "100%",
-            boxShadow: `0 0 10px ${computedGlowColor}, 0 0 5px ${computedGlowColor}`,
-            opacity: 1,
-            transform: "rotate(3deg) translate(0px, -4px)"
-          }
-        }
-      )
+var TopProgress = (0, import_react.forwardRef)(
+  ({
+    progress: controlledProgress,
+    color = "red",
+    shadow = true,
+    height = 2,
+    background = "transparent",
+    style,
+    containerStyle,
+    shadowStyle,
+    transitionTime = 300,
+    loaderSpeed = 500,
+    waitingTime = 1e3,
+    className,
+    containerClassName,
+    onLoaderFinished,
+    showGlow,
+    glowColor,
+    zIndex = 9999
+  }, ref) => {
+    const store = useProgressStore();
+    const [internalProgress, setInternalProgress] = (0, import_react.useState)(
+      store.getValue()
+    );
+    (0, import_react.useImperativeHandle)(ref, () => ({
+      start: (type) => store.start(type),
+      continuousStart: (s, r) => store.continuousStart(s, r),
+      staticStart: (s) => store.staticStart(s),
+      complete: () => store.complete(),
+      increase: (v) => store.increase(v),
+      decrease: (v) => store.decrease(v),
+      getProgress: () => store.getProgress(),
+      set: (v) => store.set(v)
+    }));
+    (0, import_react.useEffect)(() => {
+      store.config.transitionTime = transitionTime;
+      store.config.loaderSpeed = loaderSpeed;
+      store.config.waitingTime = waitingTime;
+    }, [transitionTime, loaderSpeed, waitingTime, store]);
+    (0, import_react.useEffect)(() => {
+      return store.subscribe(setInternalProgress);
+    }, [store]);
+    const progress = controlledProgress !== void 0 ? controlledProgress : internalProgress;
+    (0, import_react.useEffect)(() => {
+      if (progress === 100 && onLoaderFinished) {
+        onLoaderFinished();
+      }
+    }, [progress, onLoaderFinished]);
+    if (progress === null) {
+      return null;
     }
-  );
-};
+    const isGradient = color.includes("gradient(");
+    const backgroundStyle = isGradient ? { backgroundImage: color } : { backgroundColor: color };
+    const useShadow = showGlow !== void 0 ? showGlow : shadow;
+    const computedGlowColor = glowColor || (isGradient ? "rgba(41, 216, 255, 0.4)" : color);
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "div",
+      {
+        className: containerClassName,
+        style: {
+          position: "fixed",
+          top: 0,
+          left: 0,
+          width: "100%",
+          height: `${height}px`,
+          backgroundColor: background,
+          zIndex,
+          pointerEvents: "none",
+          ...containerStyle
+        },
+        children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "div",
+          {
+            className,
+            style: {
+              width: `${progress}%`,
+              height: "100%",
+              ...backgroundStyle,
+              transition: `width ${loaderSpeed}ms cubic-bezier(0.4, 0, 0.2, 1), opacity ${transitionTime}ms ease`,
+              opacity: progress === 100 ? 0 : 1,
+              transform: "translateZ(0)",
+              ...style
+            },
+            children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+              "div",
+              {
+                style: {
+                  display: useShadow ? "block" : "none",
+                  position: "absolute",
+                  right: 0,
+                  top: 0,
+                  width: 100,
+                  height: "100%",
+                  boxShadow: `0 0 10px ${computedGlowColor}, 0 0 5px ${computedGlowColor}`,
+                  opacity: 1,
+                  transform: "rotate(3deg) translate(0px, -4px)",
+                  ...shadowStyle
+                }
+              }
+            )
+          }
+        )
+      }
+    );
+  }
+);
+TopProgress.displayName = "TopProgress";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   TopProgress,
+  completeProgress,
+  continuousStart,
+  decreaseProgress,
   finishProgress,
+  getProgress,
+  increaseProgress,
+  setProgress,
   startProgress,
+  staticStart,
   withProgress
 });

package/dist/index.mjs

@@ -1,7 +1,12 @@
 "use client";
 
 // src/TopProgress.tsx
-import { useEffect, useState } from "react";
+import {
+  useEffect,
+  useState,
+  forwardRef,
+  useImperativeHandle
+} from "react";
 
 // src/progressStore.ts
 var ProgressStore = class {
@@ -9,6 +14,11 @@ var ProgressStore = class {
   value = null;
   interval = null;
   hideTimer = null;
+  config = {
+    transitionTime: 300,
+    loaderSpeed: 500,
+    waitingTime: 1e3
+  };
   subscribe(listener) {
     this.listeners.add(listener);
     listener(this.value);
@@ -19,27 +29,63 @@ var ProgressStore = class {
   notify() {
     this.listeners.forEach((listener) => listener(this.value));
   }
-  start() {
-    if (this.value !== null) return;
+  start(loaderType = "continuous") {
+    if (loaderType === "static") {
+      this.staticStart();
+    } else {
+      this.continuousStart();
+    }
+  }
+  continuousStart(startingValue, refreshRate) {
     this.cleanup();
-    this.value = 10;
+    this.value = startingValue !== void 0 ? startingValue : Math.floor(Math.random() * 10) + 20;
     this.notify();
     this.interval = setInterval(() => {
-      if (this.value !== null) {
-        const amount = Math.max(0.5, (95 - this.value) / 10);
-        this.value = Math.min(this.value + amount, 95);
+      if (this.value !== null && this.value < 90) {
+        const inc = Math.floor(Math.random() * 8) + 2;
+        this.value = Math.min(this.value + inc, 90);
         this.notify();
       }
-    }, 200);
+    }, refreshRate || this.config.loaderSpeed);
+  }
+  staticStart(startingValue) {
+    this.cleanup();
+    this.value = startingValue !== void 0 ? startingValue : Math.floor(Math.random() * 20) + 30;
+    this.notify();
+  }
+  complete() {
+    this.finish();
   }
   finish() {
     this.cleanup();
+    if (this.value === null) return;
     this.value = 100;
     this.notify();
     this.hideTimer = setTimeout(() => {
       this.value = null;
       this.notify();
-    }, 400);
+    }, this.config.waitingTime);
+  }
+  set(value) {
+    this.cleanup();
+    this.value = value;
+    this.notify();
+    if (value >= 100) {
+      this.finish();
+    }
+  }
+  increase(amount) {
+    if (this.value !== null) {
+      this.value = Math.min(this.value + amount, 100);
+      this.notify();
+      if (this.value === 100) this.finish();
+    }
+  }
+  decrease(amount) {
+    if (this.value !== null) {
+      this.value = Math.max(0, this.value - amount);
+      this.notify();
+    }
   }
   cleanup() {
     if (this.interval) clearInterval(this.interval);
@@ -48,11 +94,21 @@ var ProgressStore = class {
   getValue() {
     return this.value;
   }
+  getProgress() {
+    return this.value;
+  }
 };
 var progressStore = new ProgressStore();
 var useProgressStore = () => progressStore;
-var startProgress = () => progressStore.start();
+var startProgress = (type) => progressStore.start(type);
+var continuousStart = (startingValue, refreshRate) => progressStore.continuousStart(startingValue, refreshRate);
+var staticStart = (startingValue) => progressStore.staticStart(startingValue);
 var finishProgress = () => progressStore.finish();
+var completeProgress = () => progressStore.complete();
+var increaseProgress = (value) => progressStore.increase(value);
+var decreaseProgress = (value) => progressStore.decrease(value);
+var getProgress = () => progressStore.getProgress();
+var setProgress = (value) => progressStore.set(value);
 var withProgress = async (promise) => {
   startProgress();
   try {
@@ -67,68 +123,123 @@ var withProgress = async (promise) => {
 
 // src/TopProgress.tsx
 import { jsx } from "react/jsx-runtime";
-var TopProgress = ({
-  color = "#29D",
-  // Still the default flat color, but can now accept "linear-gradient(...)"
-  height = 3,
-  showGlow = true,
-  glowColor,
-  zIndex = 9999
-}) => {
-  const store = useProgressStore();
-  const [progress, setProgress] = useState(store.getValue());
-  useEffect(() => {
-    return store.subscribe(setProgress);
-  }, [store]);
-  if (progress === null) {
-    return null;
-  }
-  const isGradient = color.includes("gradient(");
-  const backgroundStyle = isGradient ? { backgroundImage: color } : { backgroundColor: color };
-  const computedGlowColor = glowColor || (isGradient ? "rgba(41, 216, 255, 0.4)" : color);
-  return /* @__PURE__ */ jsx(
-    "div",
-    {
-      style: {
-        position: "fixed",
-        top: 0,
-        left: 0,
-        width: `${progress}%`,
-        height: `${height}px`,
-        ...backgroundStyle,
-        // Box shadow generates a beautiful diffused glow underneath the progress bar
-        boxShadow: showGlow ? `0 0 10px ${computedGlowColor}, 0 0 5px ${computedGlowColor}` : "none",
-        // Smooth and performant 60fps CSS transitions
-        transition: "width 0.2s cubic-bezier(0.4, 0, 0.2, 1), opacity 0.4s ease",
-        opacity: progress === 100 ? 0 : 1,
-        zIndex,
-        // Force hardware acceleration for paint performance
-        transform: "translateZ(0)",
-        // Don't intercept clicks
-        pointerEvents: "none"
-      },
-      children: /* @__PURE__ */ jsx(
-        "div",
-        {
-          style: {
-            display: showGlow ? "block" : "none",
-            position: "absolute",
-            right: 0,
-            top: 0,
-            width: 100,
-            height: "100%",
-            boxShadow: `0 0 10px ${computedGlowColor}, 0 0 5px ${computedGlowColor}`,
-            opacity: 1,
-            transform: "rotate(3deg) translate(0px, -4px)"
-          }
-        }
-      )
+var TopProgress = forwardRef(
+  ({
+    progress: controlledProgress,
+    color = "red",
+    shadow = true,
+    height = 2,
+    background = "transparent",
+    style,
+    containerStyle,
+    shadowStyle,
+    transitionTime = 300,
+    loaderSpeed = 500,
+    waitingTime = 1e3,
+    className,
+    containerClassName,
+    onLoaderFinished,
+    showGlow,
+    glowColor,
+    zIndex = 9999
+  }, ref) => {
+    const store = useProgressStore();
+    const [internalProgress, setInternalProgress] = useState(
+      store.getValue()
+    );
+    useImperativeHandle(ref, () => ({
+      start: (type) => store.start(type),
+      continuousStart: (s, r) => store.continuousStart(s, r),
+      staticStart: (s) => store.staticStart(s),
+      complete: () => store.complete(),
+      increase: (v) => store.increase(v),
+      decrease: (v) => store.decrease(v),
+      getProgress: () => store.getProgress(),
+      set: (v) => store.set(v)
+    }));
+    useEffect(() => {
+      store.config.transitionTime = transitionTime;
+      store.config.loaderSpeed = loaderSpeed;
+      store.config.waitingTime = waitingTime;
+    }, [transitionTime, loaderSpeed, waitingTime, store]);
+    useEffect(() => {
+      return store.subscribe(setInternalProgress);
+    }, [store]);
+    const progress = controlledProgress !== void 0 ? controlledProgress : internalProgress;
+    useEffect(() => {
+      if (progress === 100 && onLoaderFinished) {
+        onLoaderFinished();
+      }
+    }, [progress, onLoaderFinished]);
+    if (progress === null) {
+      return null;
     }
-  );
-};
+    const isGradient = color.includes("gradient(");
+    const backgroundStyle = isGradient ? { backgroundImage: color } : { backgroundColor: color };
+    const useShadow = showGlow !== void 0 ? showGlow : shadow;
+    const computedGlowColor = glowColor || (isGradient ? "rgba(41, 216, 255, 0.4)" : color);
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: containerClassName,
+        style: {
+          position: "fixed",
+          top: 0,
+          left: 0,
+          width: "100%",
+          height: `${height}px`,
+          backgroundColor: background,
+          zIndex,
+          pointerEvents: "none",
+          ...containerStyle
+        },
+        children: /* @__PURE__ */ jsx(
+          "div",
+          {
+            className,
+            style: {
+              width: `${progress}%`,
+              height: "100%",
+              ...backgroundStyle,
+              transition: `width ${loaderSpeed}ms cubic-bezier(0.4, 0, 0.2, 1), opacity ${transitionTime}ms ease`,
+              opacity: progress === 100 ? 0 : 1,
+              transform: "translateZ(0)",
+              ...style
+            },
+            children: /* @__PURE__ */ jsx(
+              "div",
+              {
+                style: {
+                  display: useShadow ? "block" : "none",
+                  position: "absolute",
+                  right: 0,
+                  top: 0,
+                  width: 100,
+                  height: "100%",
+                  boxShadow: `0 0 10px ${computedGlowColor}, 0 0 5px ${computedGlowColor}`,
+                  opacity: 1,
+                  transform: "rotate(3deg) translate(0px, -4px)",
+                  ...shadowStyle
+                }
+              }
+            )
+          }
+        )
+      }
+    );
+  }
+);
+TopProgress.displayName = "TopProgress";
 export {
   TopProgress,
+  completeProgress,
+  continuousStart,
+  decreaseProgress,
   finishProgress,
+  getProgress,
+  increaseProgress,
+  setProgress,
   startProgress,
+  staticStart,
   withProgress
 };

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "react-top-progress",
-  "version": "0.1.1",
+  "version": "1.0.1",
   "description": "A lightweight modern top loading progress bar for React",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "demo_react_top_progress.png"
+    "demo_react_top_progress.webp"
   ],
   "keywords": [
     "react",