0
# Ref-based Control
1

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

4
## Setup
5

6
Create a ref and attach it to the LoadingBar component:
7

8
```typescript
9
import React, { useRef } from "react";
10
import LoadingBar, { LoadingBarRef } from "react-top-loading-bar";
11

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

15
  return (
16
    <div>
17
      <LoadingBar color="#f11946" ref={ref} shadow={true} />
18
      {/* Control buttons */}
19
    </div>
20
  );
21
};
22
```
23

24
## LoadingBarRef Interface
25

26
The ref provides access to all loading bar control methods:
27

28
```typescript { .api }
29
interface LoadingBarRef {
30
  continuousStart(startingValue?: number, refreshRate?: number): void;
31
  staticStart(startingValue?: number): void;
32
  start(type?: "continuous" | "static", startingValue?: number, refreshRate?: number): void;
33
  complete(): void;
34
  increase(value: number): void;
35
  decrease(value: number): void;
36
  getProgress(): number;
37
}
38
```
39

40
## Ref Methods
41

42
### Start Methods
43

44
```typescript { .api }
45
/**
46
 * Start continuous loading with auto-increment
47
 * @param startingValue - Initial progress value (default: random 10-20)
48
 * @param refreshRate - Auto-increment interval in ms (default: 1000)
49
 */
50
continuousStart(startingValue?: number, refreshRate?: number): void;
51

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

58
/**
59
 * Generic start method with type selection
60
 * @param type - "continuous" (default) or "static"
61
 * @param startingValue - Initial progress value
62
 * @param refreshRate - Auto-increment interval (continuous mode only)
63
 */
64
start(type?: "continuous" | "static", startingValue?: number, refreshRate?: number): void;
65
```
66

67
### Control Methods
68

69
```typescript { .api }
70
/**
71
 * Complete loading animation (animate to 100% then fade)
72
 */
73
complete(): void;
74

75
/**
76
 * Increase progress by specified amount
77
 * @param value - Amount to add to current progress
78
 */
79
increase(value: number): void;
80

81
/**
82
 * Decrease progress by specified amount
83
 * @param value - Amount to subtract from current progress
84
 */
85
decrease(value: number): void;
86

87
/**
88
 * Get current progress value
89
 * @returns Current progress percentage (0-100)
90
 */
91
getProgress(): number;
92
```
93

94
## Usage Examples
95

96
### Basic Continuous Loading
97

98
```typescript
99
const App = () => {
100
  const ref = useRef<LoadingBarRef>(null);
101

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

106
  return (
107
    <div>
108
      <LoadingBar color="blue" ref={ref} />
109
      <button onClick={startContinuous}>Start Continuous</button>
110
      <button onClick={() => ref.current?.complete()}>Complete</button>
111
    </div>
112
  );
113
};
114
```
115

116
### Static Progress Control
117

118
```typescript
119
const StaticExample = () => {
120
  const ref = useRef<LoadingBarRef>(null);
121

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

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

130
  return (
131
    <div>
132
      <LoadingBar color="red" ref={ref} height={4} />
133
      <button onClick={handleStaticStart}>Start at 50%</button>
134
      <button onClick={handleIncrease}>+10%</button>
135
      <button onClick={() => ref.current?.complete()}>Complete</button>
136
    </div>
137
  );
138
};
139
```
140

141
### Generic Start Method
142

143
```typescript
144
const GenericExample = () => {
145
  const ref = useRef<LoadingBarRef>(null);
146

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

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

155
  return (
156
    <div>
157
      <LoadingBar color="green" ref={ref} />
158
      <button onClick={startContinuous}>Continuous (15%, 800ms)</button>
159
      <button onClick={startStatic}>Static (40%)</button>
160
    </div>
161
  );
162
};
163
```
164

165
### Progress Monitoring
166

167
```typescript
168
const ProgressMonitor = () => {
169
  const ref = useRef<LoadingBarRef>(null);
170
  const [progress, setProgress] = useState(0);
171

172
  const updateProgress = () => {
173
    const current = ref.current?.getProgress() || 0;
174
    setProgress(current);
175
  };
176

177
  useEffect(() => {
178
    const interval = setInterval(updateProgress, 100);
179
    return () => clearInterval(interval);
180
  }, []);
181

182
  return (
183
    <div>
184
      <LoadingBar color="purple" ref={ref} />
185
      <p>Current Progress: {progress}%</p>
186
      <button onClick={() => ref.current?.continuousStart()}>Start</button>
187
    </div>
188
  );
189
};
190
```
191

192
### File Upload Progress
193

194
```typescript
195
const FileUploadExample = () => {
196
  const ref = useRef<LoadingBarRef>(null);
197

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

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

204
    try {
205
      const response = await fetch("/upload", {
206
        method: "POST",
207
        body: formData,
208
      });
209

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

216
      ref.current?.complete();
217
    } catch (error) {
218
      ref.current?.complete();
219
    }
220
  };
221

222
  return (
223
    <div>
224
      <LoadingBar color="orange" ref={ref} height={3} />
225
      <input
226
        type="file"
227
        onChange={(e) => e.target.files?.[0] && uploadFile(e.target.files[0])}
228
      />
229
    </div>
230
  );
231
};
232
```
233

234
## Configuration
235

236
Configure the loading bar appearance through component props:
237

238
```typescript
239
<LoadingBar
240
  ref={ref}
241
  color="#ff6b6b"
242
  height={5}
243
  shadow={true}
244
  background="rgba(0,0,0,0.1)"
245
  loaderSpeed={400}
246
  transitionTime={200}
247
  waitingTime={800}
248
  onLoaderFinished={() => console.log("Loading complete!")}
249
/>
250
```
251

252
## Important Notes
253

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