0
# Imperative Progress Control
1

2
The imperative progress control API provides functions for programmatic control of progress state, enabling integration with routing libraries, async operations, and custom navigation flows.
3

4
## Capabilities
5

6
### Start Progress
7

8
Begins automatic progress increments with variable speed based on current progress value.
9

10
```typescript { .api }
11
/**
12
 * Starts automatic progress increments using intervals
13
 * Progress speed varies: fast initially (10), then slower as it approaches completion
14
 */
15
function startNavigationProgress(): void;
16
```
17

18
**Usage Examples:**
19

20
```typescript
21
import { startNavigationProgress } from "@mantine/nprogress";
22

23
// Start progress on navigation
24
function handleRouteChange() {
25
  startNavigationProgress();
26
}
27

28
// Integration with Next.js router
29
import { useRouter } from "next/router";
30

31
function useProgressOnRouteChange() {
32
  const router = useRouter();
33
  
34
  useEffect(() => {
35
    const handleStart = () => startNavigationProgress();
36
    router.events.on('routeChangeStart', handleStart);
37
    
38
    return () => router.events.off('routeChangeStart', handleStart);
39
  }, [router]);
40
}
41
```
42

43
### Stop Progress
44

45
Stops automatic progress increments without changing current progress value.
46

47
```typescript { .api }
48
/**
49
 * Stops automatic progress increments by clearing the interval
50
 * Progress value remains at current position
51
 */
52
function stopNavigationProgress(): void;
53
```
54

55
**Usage Examples:**
56

57
```typescript
58
import { stopNavigationProgress } from "@mantine/nprogress";
59

60
// Stop progress on user action
61
function handleUserPause() {
62
  stopNavigationProgress();
63
}
64

65
// Conditional stopping
66
function handleConditionalStop(shouldStop: boolean) {
67
  if (shouldStop) {
68
    stopNavigationProgress();
69
  }
70
}
71
```
72

73
### Set Progress Value
74

75
Sets progress to a specific value between 0 and 100.
76

77
```typescript { .api }
78
/**
79
 * Sets progress to a specific value and makes progress bar visible
80
 * @param value - Progress value (automatically clamped to 0-100 range)
81
 */
82
function setNavigationProgress(value: number): void;
83
```
84

85
**Usage Examples:**
86

87
```typescript
88
import { setNavigationProgress } from "@mantine/nprogress";
89

90
// Set specific progress value
91
setNavigationProgress(45);
92

93
// Track upload progress
94
function handleUploadProgress(progressEvent: ProgressEvent) {
95
  const percentComplete = (progressEvent.loaded / progressEvent.total) * 100;
96
  setNavigationProgress(percentComplete);
97
}
98

99
// Step-by-step progress
100
const steps = ['Loading', 'Processing', 'Finalizing'];
101
function updateStepProgress(currentStep: number) {
102
  const progress = ((currentStep + 1) / steps.length) * 100;
103
  setNavigationProgress(progress);
104
}
105
```
106

107
### Increment Progress
108

109
Increases progress by the current step amount.
110

111
```typescript { .api }
112
/**
113
 * Increases progress by the step amount (default 1)
114
 * Automatically handles completion and reset when reaching 100%
115
 */
116
function incrementNavigationProgress(): void;
117
```
118

119
**Usage Examples:**
120

121
```typescript
122
import { incrementNavigationProgress } from "@mantine/nprogress";
123

124
// Manual progress increments
125
function handleTaskCompletion() {
126
  incrementNavigationProgress();
127
}
128

129
// Batch processing progress
130
async function processBatch(items: any[]) {
131
  for (const item of items) {
132
    await processItem(item);
133
    incrementNavigationProgress();
134
  }
135
}
136
```
137

138
### Decrement Progress
139

140
Decreases progress by the current step amount.
141

142
```typescript { .api }
143
/**
144
 * Decreases progress by the step amount, minimum value is 0
145
 */
146
function decrementNavigationProgress(): void;
147
```
148

149
**Usage Examples:**
150

151
```typescript
152
import { decrementNavigationProgress } from "@mantine/nprogress";
153

154
// Handle progress reversal
155
function handleUndo() {
156
  decrementNavigationProgress();
157
}
158

159
// Error handling with progress rollback
160
function handleProcessingError() {
161
  decrementNavigationProgress();
162
  console.log("Process failed, rolling back progress");
163
}
164
```
165

166
### Complete Progress
167

168
Completes progress with smooth animation and automatic cleanup.
169

170
```typescript { .api }
171
/**
172
 * Sets progress to 100%, waits briefly, then hides and resets
173
 * Includes automatic cleanup of intervals and timeouts
174
 */
175
function completeNavigationProgress(): void;
176
```
177

178
**Usage Examples:**
179

180
```typescript
181
import { completeNavigationProgress } from "@mantine/nprogress";
182

183
// Complete progress on successful navigation
184
function handleRouteChangeComplete() {
185
  completeNavigationProgress();
186
}
187

188
// Complete progress after async operation
189
async function handleAsyncOperation() {
190
  try {
191
    await performOperation();
192
    completeNavigationProgress();
193
  } catch (error) {
194
    resetNavigationProgress();
195
  }
196
}
197

198
// Integration with fetch requests
199
async function handleApiRequest() {
200
  startNavigationProgress();
201
  
202
  try {
203
    const response = await fetch('/api/data');
204
    const data = await response.json();
205
    completeNavigationProgress();
206
    return data;
207
  } catch (error) {
208
    resetNavigationProgress();
209
    throw error;
210
  }
211
}
212
```
213

214
### Reset Progress
215

216
Immediately resets progress to 0 and hides the progress bar.
217

218
```typescript { .api }
219
/**
220
 * Immediately resets progress to 0, hides progress bar, and cleans up
221
 * Clears all active intervals and timeouts
222
 */
223
function resetNavigationProgress(): void;
224
```
225

226
**Usage Examples:**
227

228
```typescript
229
import { resetNavigationProgress } from "@mantine/nprogress";
230

231
// Reset on navigation error
232
function handleNavigationError() {
233
  resetNavigationProgress();
234
}
235

236
// Reset on component unmount
237
useEffect(() => {
238
  return () => resetNavigationProgress();
239
}, []);
240
```
241

242
### Cleanup Resources  
243

244
Clears all active intervals and timeouts without changing progress state.
245

246
```typescript { .api }
247
/**
248
 * Clears active intervals and timeouts for resource cleanup
249
 * Progress value and visibility state remain unchanged
250
 */
251
function cleanupNavigationProgress(): void;
252
```
253

254
**Usage Examples:**
255

256
```typescript
257
import { cleanupNavigationProgress } from "@mantine/nprogress";
258

259
// Manual cleanup before component unmount
260
function handleComponentCleanup() {
261
  cleanupNavigationProgress();
262
}
263

264
// Cleanup before starting new progress sequence
265
function handleNewSequence() {
266
  cleanupNavigationProgress();
267
  startNavigationProgress();
268
}
269
```
270

271
## Usage Patterns
272

273
### Router Integration
274

275
```typescript
276
import { 
277
  startNavigationProgress, 
278
  completeNavigationProgress, 
279
  resetNavigationProgress 
280
} from "@mantine/nprogress";
281

282
// Next.js integration
283
router.events.on('routeChangeStart', startNavigationProgress);
284
router.events.on('routeChangeComplete', completeNavigationProgress);
285
router.events.on('routeChangeError', resetNavigationProgress);
286

287
// React Router integration (with history)
288
history.listen(() => {
289
  startNavigationProgress();
290
  // Complete when component loads
291
  setTimeout(completeNavigationProgress, 100);
292
});
293
```
294

295
### Async Operation Tracking
296

297
```typescript
298
async function trackAsyncOperation<T>(operation: () => Promise<T>): Promise<T> {
299
  startNavigationProgress();
300
  
301
  try {
302
    const result = await operation();
303
    completeNavigationProgress();
304
    return result;
305
  } catch (error) {
306
    resetNavigationProgress();
307
    throw error;
308
  }
309
}
310

311
// Usage
312
await trackAsyncOperation(async () => {
313
  const data = await fetchUserData();
314
  await processUserData(data);
315
  return data;
316
});
317
```
318

319
### Manual Progress Control
320

321
```typescript
322
// Step-by-step progress tracking
323
const totalSteps = 5;
324
let currentStep = 0;
325

326
function nextStep() {
327
  currentStep++;
328
  const progress = (currentStep / totalSteps) * 100;
329
  setNavigationProgress(progress);
330
  
331
  if (currentStep === totalSteps) {
332
    setTimeout(completeNavigationProgress, 500);
333
  }
334
}
335
```