0
# Progress State Management
1

2
The progress state management system provides the core store functionality for tracking progress state, managing intervals and timeouts, and enabling React integration through hooks.
3

4
## Capabilities
5

6
### Store Creation
7

8
Factory function for creating new progress store instances.
9

10
```typescript { .api }
11
/**
12
 * Creates a new progress store with default initial state
13
 * @returns New NprogressStore instance
14
 */
15
function createNprogressStore(): NprogressStore;
16
```
17

18
**Usage Examples:**
19

20
```typescript
21
import { createNprogressStore, useNprogress } from "@mantine/nprogress";
22

23
// Create isolated store for specific component
24
const myStore = createNprogressStore();
25

26
// Use in React component
27
function MyComponent() {
28
  const state = useNprogress(myStore);
29
  
30
  return (
31
    <div>
32
      Progress: {state.progress}%
33
      {state.mounted && <div>Progress bar is visible</div>}
34
    </div>
35
  );
36
}
37
```
38

39
### React Hook Integration
40

41
Hook for subscribing to store state changes in React components.
42

43
```typescript { .api }
44
/**
45
 * React hook to subscribe to progress store state changes
46
 * @param store - The progress store to subscribe to
47
 * @returns Current state of the progress store
48
 */
49
function useNprogress(store: NprogressStore): NprogressState;
50
```
51

52
**Usage Examples:**
53

54
```typescript
55
import { useNprogress, nprogressStore } from "@mantine/nprogress";
56

57
// Using default store
58
function ProgressDisplay() {
59
  const state = useNprogress(nprogressStore);
60
  
61
  return (
62
    <div>
63
      <div>Current Progress: {state.progress}%</div>
64
      <div>Mounted: {state.mounted ? 'Yes' : 'No'}</div>
65
      <div>Step Interval: {state.stepInterval}ms</div>
66
    </div>
67
  );
68
}
69

70
// Using custom store
71
import { createNprogressStore } from "@mantine/nprogress";
72

73
const customStore = createNprogressStore();
74

75
function CustomProgressDisplay() {
76
  const state = useNprogress(customStore);
77
  // ... use state
78
}
79
```
80

81
### Default Store Instance
82

83
Pre-created global store instance for simple usage scenarios.
84

85
```typescript { .api }
86
/** Default shared store instance for global progress control */
87
const nprogressStore: NprogressStore;
88
```
89

90
**Usage Examples:**
91

92
```typescript
93
import { nprogressStore, useNprogress } from "@mantine/nprogress";
94

95
// Direct store access
96
console.log(nprogressStore.getState());
97

98
// React hook usage
99
function GlobalProgressMonitor() {
100
  const state = useNprogress(nprogressStore);
101
  return <div>Global Progress: {state.progress}%</div>;
102
}
103
```
104

105
### Low-Level State Updates
106

107
Low-level function for updating store state with custom logic.
108

109
```typescript { .api }
110
/**
111
 * Updates progress store state using a partial state updater function
112
 * @param update - Function that receives current state and returns partial state update
113
 * @param store - The progress store to update
114
 */
115
function updateNavigationProgressStateAction(
116
  update: (state: NprogressState) => Partial<NprogressState>,
117
  store: NprogressStore
118
): void;
119
```
120

121
**Usage Examples:**
122

123
```typescript
124
import { updateNavigationProgressStateAction, nprogressStore } from "@mantine/nprogress";
125

126
// Custom state update
127
updateNavigationProgressStateAction(
128
  (state) => ({ 
129
    progress: Math.min(state.progress + 25, 100),
130
    mounted: true 
131
  }),
132
  nprogressStore
133
);
134

135
// Conditional state update
136
updateNavigationProgressStateAction(
137
  (state) => {
138
    if (state.progress >= 90) {
139
      return { progress: 100, mounted: false };
140
    }
141
    return { progress: state.progress + 10 };
142
  },
143
  nprogressStore
144
);
145
```
146

147
## Types
148

149
```typescript { .api }
150
/** Progress store state structure */
151
interface NprogressState {
152
  /** Whether the progress bar is currently visible */
153
  mounted: boolean;
154
  
155
  /** Current progress value (0-100) */
156
  progress: number;
157
  
158
  /** Window interval ID for automatic progress increments */
159
  interval: number;
160
  
161
  /** Progress increment step size */
162
  step: number;
163
  
164
  /** Time between automatic progress increments in milliseconds */
165
  stepInterval: number;
166
  
167
  /** Array of active timeout IDs for cleanup */
168
  timeouts: number[];
169
}
170

171
/** Progress store type extending Mantine's store system */
172
type NprogressStore = MantineStore<NprogressState>;
173
```
174

175
### Default State Values
176

177
When creating a new store with `createNprogressStore()`, the following default values are used:
178

179
```typescript
180
{
181
  mounted: false,
182
  progress: 0,
183
  interval: 0,
184
  step: 1,
185
  stepInterval: 100,  // Note: NavigationProgress component defaults to 500ms
186
  timeouts: []
187
}
188
```
189

190
**Important:** The `NavigationProgress` component uses a default `stepInterval` of 500ms in its props, which overwrites the store default when the component initializes the store.
191

192
### State Management Patterns
193

194
**Reading State:**
195
```typescript
196
// Get current state snapshot
197
const currentState = store.getState();
198

199
// Subscribe to state changes in React
200
const state = useNprogress(store);
201
```
202

203
**Updating State:**
204
```typescript
205
// Direct state replacement
206
store.setState({ progress: 50, mounted: true });
207

208
// Partial state update with merge
209
updateNavigationProgressStateAction(
210
  (state) => ({ progress: state.progress + 10 }),
211
  store
212
);
213
```
214

215
**Cleanup Management:**
216
```typescript
217
// Store tracks timeouts for proper cleanup
218
updateNavigationProgressStateAction(
219
  (state) => {
220
    const timeout = setTimeout(() => {
221
      // Some delayed action
222
    }, 1000);
223
    
224
    return {
225
      timeouts: [...state.timeouts, timeout]
226
    };
227
  },
228
  store
229
);
230
```