0
# react-top-loading-bar
1

2
## Overview
3

4
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.
5

6
## Package Information
7

8
- **Name**: react-top-loading-bar
9
- **Type**: React Component Library
10
- **Language**: TypeScript
11
- **Version**: 3.0.2
12
- **License**: MIT
13

14
### Installation
15

16
**npm:**
17
```bash
18
npm install react-top-loading-bar
19
```
20

21
**yarn:**
22
```bash
23
yarn add react-top-loading-bar
24
```
25

26
**CDN:**
27
```bash
28
https://unpkg.com/react-top-loading-bar
29
```
30

31
## Core Imports
32

33
```typescript { .api }
34
// ESM (preferred)
35
import LoadingBar, { 
36
  LoadingBarRef, 
37
  LoadingBarContainer, 
38
  useLoadingBar,
39
  type IProps 
40
} from "react-top-loading-bar";
41

42
// CommonJS
43
const LoadingBar = require("react-top-loading-bar").default;
44
const { LoadingBarContainer, useLoadingBar } = require("react-top-loading-bar");
45
```
46

47
## Basic Usage
48

49
The most common usage pattern with hooks:
50

51
```typescript
52
import React from "react";
53
import { LoadingBarContainer, useLoadingBar } from "react-top-loading-bar";
54

55
const App = () => {
56
  const { start, complete } = useLoadingBar({
57
    color: "blue",
58
    height: 3,
59
  });
60

61
  return (
62
    <div>
63
      <button onClick={() => start()}>Start Loading</button>
64
      <button onClick={() => complete()}>Complete</button>
65
    </div>
66
  );
67
};
68

69
const Parent = () => (
70
  <LoadingBarContainer>
71
    <App />
72
  </LoadingBarContainer>
73
);
74
```
75

76
## Architecture
77

78
The library is built around three core components:
79

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

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

86
## Component Props Interface
87

88
```typescript { .api }
89
interface IProps {
90
  // Progress Control
91
  progress?: number;
92
  onLoaderFinished?: () => void;
93
  
94
  // Visual Styling
95
  color?: string;
96
  background?: string;
97
  height?: number;
98
  shadow?: boolean;
99
  className?: string;
100
  containerClassName?: string;
101
  style?: CSSProperties;
102
  containerStyle?: CSSProperties;
103
  shadowStyle?: CSSProperties;
104
  
105
  // Animation Timing
106
  loaderSpeed?: number;
107
  transitionTime?: number;
108
  waitingTime?: number;
109
}
110
```
111

112
## Ref Control Interface
113

114
```typescript { .api }
115
interface LoadingBarRef {
116
  // Start Methods
117
  continuousStart(startingValue?: number, refreshRate?: number): void;
118
  staticStart(startingValue?: number): void;
119
  start(type?: "continuous" | "static", startingValue?: number, refreshRate?: number): void;
120
  
121
  // Control Methods  
122
  complete(): void;
123
  increase(value: number): void;
124
  decrease(value: number): void;
125
  getProgress(): number;
126
}
127
```
128

129
## Implementation Patterns
130

131
### [Hook-based Control](./hook-based-control.md)
132
Use the `useLoadingBar` hook within a `LoadingBarContainer` for declarative loading bar control with React context.
133

134
### [Ref-based Control](./ref-based-control.md)
135
Use React refs with the `LoadingBarRef` interface for imperative control over the loading bar with direct method calls.
136

137
### [State-based Control](./state-based-control.md)
138
Use the controlled component pattern by managing progress state and passing it as a prop to the LoadingBar component.
139

140
## Visual Customization
141

142
The loading bar supports extensive visual customization:
143

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

150
## Animation Control
151

152
Fine-tune loading animations with timing properties:
153

154
- **loaderSpeed**: Transition speed in milliseconds (default: 500ms)
155
- **transitionTime**: Fade transition time in milliseconds (default: 300ms)  
156
- **waitingTime**: Delay before fade out in milliseconds (default: 1000ms)
157

158
## Loading Modes
159

160
Two distinct loading modes provide different user experience patterns:
161

162
- **Continuous**: Automatically increments progress with configurable refresh rate
163
- **Static**: Maintains fixed progress value until manually changed
164

165
Both modes support custom starting values and complete visual customization.