tessl/npm-react-top-loading-bar

A highly customizable React top-loading bar component with hook-based, ref-based, and state-based control patterns.

1.25x

Overview

Eval results

Files

Ref-based Control

Name: tessl/npm-react-top-loading-bar
Rating: 0.64 (1 reviews)
Author: tessl

The ref-based approach provides imperative control over the loading bar through React refs, offering direct method access for precise programmatic control.

Setup

Create a ref and attach it to the LoadingBar component:

import React, { useRef } from "react";
import LoadingBar, { LoadingBarRef } from "react-top-loading-bar";

const App = () => {
  const ref = useRef<LoadingBarRef>(null);

  return (
    <div>
      <LoadingBar color="#f11946" ref={ref} shadow={true} />
      {/* Control buttons */}
    </div>
  );
};

LoadingBarRef Interface

The ref provides access to all loading bar control methods:

interface LoadingBarRef {
  continuousStart(startingValue?: number, refreshRate?: number): void;
  staticStart(startingValue?: number): void;
  start(type?: "continuous" | "static", startingValue?: number, refreshRate?: number): void;
  complete(): void;
  increase(value: number): void;
  decrease(value: number): void;
  getProgress(): number;
}

Ref Methods

Start Methods

/**
 * Start continuous loading with auto-increment
 * @param startingValue - Initial progress value (default: random 10-20)
 * @param refreshRate - Auto-increment interval in ms (default: 1000)
 */
continuousStart(startingValue?: number, refreshRate?: number): void;

/**
 * Start static loading at fixed value
 * @param startingValue - Progress value to set (default: random 30-60)
 */
staticStart(startingValue?: number): void;

/**
 * Generic start method with type selection
 * @param type - "continuous" (default) or "static"
 * @param startingValue - Initial progress value
 * @param refreshRate - Auto-increment interval (continuous mode only)
 */
start(type?: "continuous" | "static", startingValue?: number, refreshRate?: number): void;

Control Methods

/**
 * Complete loading animation (animate to 100% then fade)
 */
complete(): void;

/**
 * Increase progress by specified amount
 * @param value - Amount to add to current progress
 */
increase(value: number): void;

/**
 * Decrease progress by specified amount
 * @param value - Amount to subtract from current progress
 */
decrease(value: number): void;

/**
 * Get current progress value
 * @returns Current progress percentage (0-100)
 */
getProgress(): number;

Usage Examples

Basic Continuous Loading

const App = () => {
  const ref = useRef<LoadingBarRef>(null);

  const startContinuous = () => {
    ref.current?.continuousStart(10, 500); // Start at 10%, increment every 500ms
  };

  return (
    <div>
      <LoadingBar color="blue" ref={ref} />
      <button onClick={startContinuous}>Start Continuous</button>
      <button onClick={() => ref.current?.complete()}>Complete</button>
    </div>
  );
};

Static Progress Control

const StaticExample = () => {
  const ref = useRef<LoadingBarRef>(null);

  const handleStaticStart = () => {
    ref.current?.staticStart(50); // Start at 50%
  };

  const handleIncrease = () => {
    ref.current?.increase(10); // Add 10%
  };

  return (
    <div>
      <LoadingBar color="red" ref={ref} height={4} />
      <button onClick={handleStaticStart}>Start at 50%</button>
      <button onClick={handleIncrease}>+10%</button>
      <button onClick={() => ref.current?.complete()}>Complete</button>
    </div>
  );
};

Generic Start Method

const GenericExample = () => {
  const ref = useRef<LoadingBarRef>(null);

  const startContinuous = () => {
    ref.current?.start("continuous", 15, 800);
  };

  const startStatic = () => {
    ref.current?.start("static", 40);
  };

  return (
    <div>
      <LoadingBar color="green" ref={ref} />
      <button onClick={startContinuous}>Continuous (15%, 800ms)</button>
      <button onClick={startStatic}>Static (40%)</button>
    </div>
  );
};

Progress Monitoring

const ProgressMonitor = () => {
  const ref = useRef<LoadingBarRef>(null);
  const [progress, setProgress] = useState(0);

  const updateProgress = () => {
    const current = ref.current?.getProgress() || 0;
    setProgress(current);
  };

  useEffect(() => {
    const interval = setInterval(updateProgress, 100);
    return () => clearInterval(interval);
  }, []);

  return (
    <div>
      <LoadingBar color="purple" ref={ref} />
      <p>Current Progress: {progress}%</p>
      <button onClick={() => ref.current?.continuousStart()}>Start</button>
    </div>
  );
};

File Upload Progress

const FileUploadExample = () => {
  const ref = useRef<LoadingBarRef>(null);

  const uploadFile = async (file: File) => {
    ref.current?.staticStart(0);

    const formData = new FormData();
    formData.append("file", file);

    try {
      const response = await fetch("/upload", {
        method: "POST",
        body: formData,
      });

      // Simulate upload progress
      for (let i = 0; i <= 100; i += 10) {
        ref.current?.increase(10);
        await new Promise(resolve => setTimeout(resolve, 100));
      }

      ref.current?.complete();
    } catch (error) {
      ref.current?.complete();
    }
  };

  return (
    <div>
      <LoadingBar color="orange" ref={ref} height={3} />
      <input
        type="file"
        onChange={(e) => e.target.files?.[0] && uploadFile(e.target.files[0])}
      />
    </div>
  );
};

Configuration

Configure the loading bar appearance through component props:

<LoadingBar
  ref={ref}
  color="#ff6b6b"
  height={5}
  shadow={true}
  background="rgba(0,0,0,0.1)"
  loaderSpeed={400}
  transitionTime={200}
  waitingTime={800}
  onLoaderFinished={() => console.log("Loading complete!")}
/>

Important Notes

Conflict Warning: Cannot use both ref methods and progress prop simultaneously. The library will warn if both are used together.
Ref Safety: Always use optional chaining (ref.current?.method()) to safely access ref methods.
Continuous vs Static: Continuous mode auto-increments progress, while static mode maintains fixed values until manually changed.
Progress Bounds: Progress values are automatically clamped between 0 and 100.

Install with Tessl CLI

npx tessl i tessl/npm-react-top-loading-bar

tessl/npm-react-top-loading-bar