0
# Hook-based Control
1

2
The hook-based approach provides declarative loading bar control through React context, offering a clean API for components that need to trigger loading states without direct access to the loading bar component.
3

4
## Setup
5

6
Wrap your application or relevant component tree with `LoadingBarContainer`:
7

8
```typescript { .api }
9
function LoadingBarContainer(props: {
10
  children: React.ReactNode;
11
  props?: Omit<IProps, "progress">;
12
}): JSX.Element;
13
```
14

15
```typescript
16
import { LoadingBarContainer } from "react-top-loading-bar";
17

18
const App = () => (
19
  <LoadingBarContainer
20
    props={{
21
      color: "blue",
22
      height: 3,
23
    }}
24
  >
25
    <MyAppComponents />
26
  </LoadingBarContainer>
27
);
28
```
29

30
## useLoadingBar Hook
31

32
Access loading bar controls from any component within the container:
33

34
```typescript { .api }
35
function useLoadingBar(props?: IProps): {
36
  start(type?: "continuous" | "static"): void;
37
  complete(): void;
38
  increase(value: number): void;
39
  decrease(value: number): void;
40
  getProgress(): number;
41
};
42
```
43

44
### Hook Methods
45

46
```typescript { .api }
47
/**
48
 * Start the loading bar
49
 * @param type - Loading mode: "continuous" (auto-increment) or "static" (fixed)
50
 */
51
start(type?: "continuous" | "static"): void;
52

53
/**
54
 * Complete the loading bar (animate to 100%)
55
 */
56
complete(): void;
57

58
/**
59
 * Increase progress by specified value
60
 * @param value - Amount to increase (0-100)
61
 */
62
increase(value: number): void;
63

64
/**
65
 * Decrease progress by specified value  
66
 * @param value - Amount to decrease (0-100)
67
 */
68
decrease(value: number): void;
69

70
/**
71
 * Get current progress value
72
 * @returns Current progress (0-100)
73
 */
74
getProgress(): number;
75
```
76

77
## Usage Examples
78

79
### Basic Loading Control
80

81
```typescript
82
import { useLoadingBar } from "react-top-loading-bar";
83

84
const ApiDataComponent = () => {
85
  const { start, complete } = useLoadingBar();
86

87
  const fetchData = async () => {
88
    start("continuous");
89
    try {
90
      await fetch("/api/data");
91
      complete();
92
    } catch (error) {
93
      complete();
94
    }
95
  };
96

97
  return <button onClick={fetchData}>Load Data</button>;
98
};
99
```
100

101
### Progress Manipulation
102

103
```typescript
104
const ProgressControlComponent = () => {
105
  const { start, increase, decrease, complete, getProgress } = useLoadingBar();
106

107
  return (
108
    <div>
109
      <button onClick={() => start("static")}>Start Static</button>
110
      <button onClick={() => increase(20)}>+20%</button>
111
      <button onClick={() => decrease(10)}>-10%</button>
112
      <button onClick={() => complete()}>Complete</button>
113
      <span>Progress: {getProgress()}%</span>
114
    </div>
115
  );
116
};
117
```
118

119
### Multiple Loading States
120

121
```typescript
122
const MultiStepProcess = () => {
123
  const { start, increase, complete } = useLoadingBar();
124

125
  const runMultiStepProcess = async () => {
126
    start("static"); // Start at random value
127
    
128
    // Step 1
129
    await step1();
130
    increase(25);
131
    
132
    // Step 2  
133
    await step2();
134
    increase(25);
135
    
136
    // Step 3
137
    await step3();
138
    increase(25);
139
    
140
    // Complete
141
    complete();
142
  };
143

144
  return <button onClick={runMultiStepProcess}>Run Process</button>;
145
};
146
```
147

148
## Container Props Configuration
149

150
Configure default loading bar appearance through container props:
151

152
```typescript
153
<LoadingBarContainer
154
  props={{
155
    color: "#ff6b6b",
156
    height: 4,
157
    shadow: true,
158
    loaderSpeed: 300,
159
    transitionTime: 400,
160
  }}
161
>
162
  <App />
163
</LoadingBarContainer>
164
```
165

166
## Hook Props Override
167

168
Override container defaults by passing props to the hook:
169

170
```typescript
171
const { start, complete } = useLoadingBar({
172
  color: "green", // Overrides container color
173
  height: 5,      // Overrides container height
174
});
175
```
176

177
## Error Handling
178

179
The hook will throw an error if used outside of a `LoadingBarContainer`:
180

181
```typescript
182
// This will throw an error
183
const { start } = useLoadingBar(); // Error: must be used within LoadingBarContainer
184
```
185

186
Always ensure components using `useLoadingBar` are wrapped in a `LoadingBarContainer`.