react-top-loading-bar

Overview

react-top-loading-bar is a highly customizable React component that provides a YouTube-style top-loading bar for indicating progress in web applications. The library offers maximum flexibility through three distinct implementation patterns: hook-based control with context, ref-based imperative control, and state-based controlled component patterns. Each approach provides complete access to the loading bar's visual styling, animation timing, and programmatic control capabilities.

Package Information

• Name: react-top-loading-bar
• Type: React Component Library
• Language: TypeScript
• Version: 3.0.2
• License: MIT

Installation

npm:

npm install react-top-loading-bar

yarn:

yarn add react-top-loading-bar

CDN:

https://unpkg.com/react-top-loading-bar

Core Imports

// ESM (preferred)
import LoadingBar, { 
  LoadingBarRef, 
  LoadingBarContainer, 
  useLoadingBar,
  type IProps 
} from "react-top-loading-bar";

// CommonJS
const LoadingBar = require("react-top-loading-bar").default;
const { LoadingBarContainer, useLoadingBar } = require("react-top-loading-bar");

Basic Usage

The most common usage pattern with hooks:

import React from "react";
import { LoadingBarContainer, useLoadingBar } from "react-top-loading-bar";

const App = () => {
  const { start, complete } = useLoadingBar({
    color: "blue",
    height: 3,
  });

  return (
    <div>
      <button onClick={() => start()}>Start Loading</button>
      <button onClick={() => complete()}>Complete</button>
    </div>
  );
};

const Parent = () => (
  <LoadingBarContainer>
    <App />
  </LoadingBarContainer>
);

Architecture

The library is built around three core components:

1. LoadingBar: The main visual component that renders the loading bar
2. LoadingBarContainer: Context provider that enables hook-based control
3. useLoadingBar: Hook for accessing loading controls within the container

The loading bar supports both continuous loading (automatically incrementing progress) and static loading (fixed progress values) with comprehensive visual customization options.

Component Props Interface

interface IProps {
  // Progress Control
  progress?: number;
  onLoaderFinished?: () => void;
  
  // Visual Styling
  color?: string;
  background?: string;
  height?: number;
  shadow?: boolean;
  className?: string;
  containerClassName?: string;
  style?: CSSProperties;
  containerStyle?: CSSProperties;
  shadowStyle?: CSSProperties;
  
  // Animation Timing
  loaderSpeed?: number;
  transitionTime?: number;
  waitingTime?: number;
}

Ref Control Interface

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

Implementation Patterns

Hook-based Control

Use the useLoadingBar hook within a LoadingBarContainer for declarative loading bar control with React context.

Ref-based Control

Use React refs with the LoadingBarRef interface for imperative control over the loading bar with direct method calls.

State-based Control

Use the controlled component pattern by managing progress state and passing it as a prop to the LoadingBar component.

Visual Customization

The loading bar supports extensive visual customization:

• Color: Any CSS color value (red, #ff0000, rgb(255,0,0))
• Height: Height in pixels (default: 2px)
• Shadow: Optional glow effect with customizable styles
• Background: Container background color (default: transparent)
• Custom CSS: Full CSS customization via className and style props

Animation Control

Fine-tune loading animations with timing properties:

• loaderSpeed: Transition speed in milliseconds (default: 500ms)
• transitionTime: Fade transition time in milliseconds (default: 300ms)
• waitingTime: Delay before fade out in milliseconds (default: 1000ms)

Loading Modes

Two distinct loading modes provide different user experience patterns:

• Continuous: Automatically increments progress with configurable refresh rate
• Static: Maintains fixed progress value until manually changed

Both modes support custom starting values and complete visual customization.