0
# Mantine Navigation Progress
1

2
Mantine Navigation Progress is a React library that provides a navigation progress bar component for indicating page loading or navigation status in web applications. It integrates seamlessly with the Mantine UI framework and offers both declarative React component patterns and imperative control methods for maximum flexibility in implementation.
3

4
## Package Information
5

6
- **Package Name**: @mantine/nprogress
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @mantine/nprogress @mantine/core @mantine/hooks`
10

11
## Core Imports
12

13
```typescript
14
import { NavigationProgress } from "@mantine/nprogress";
15
import { startNavigationProgress, completeNavigationProgress } from "@mantine/nprogress";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { NavigationProgress, startNavigationProgress, completeNavigationProgress } = require("@mantine/nprogress");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import { NavigationProgress, startNavigationProgress, completeNavigationProgress } from "@mantine/nprogress";
28
import "@mantine/nprogress/styles.css";
29

30
// Add the component to your app
31
function App() {
32
  return (
33
    <div>
34
      <NavigationProgress />
35
      {/* Your app content */}
36
    </div>
37
  );
38
}
39

40
// Control progress programmatically
41
function handleNavigation() {
42
  startNavigationProgress();
43
  
44
  // Simulate async operation
45
  setTimeout(() => {
46
    completeNavigationProgress();
47
  }, 2000);
48
}
49
```
50

51
## Architecture  
52

53
Mantine Navigation Progress is built around several key components:
54

55
- **NavigationProgress Component**: Declarative React component for rendering the progress bar with customizable appearance
56
- **Progress Store System**: State management using @mantine/store for progress tracking and lifecycle
57
- **Action Functions**: Imperative API for controlling progress (start, stop, set, complete, etc.)
58
- **Portal Rendering**: Optional portal-based rendering for proper z-index layering
59
- **Default Store Instance**: Shared global store for simple usage scenarios
60

61
## Capabilities
62

63
### NavigationProgress Component
64

65
Main React component for rendering the navigation progress bar with full customization options including colors, sizing, portal rendering, and z-index control.
66

67
```typescript { .api }
68
function NavigationProgress(props: NavigationProgressProps): JSX.Element;
69

70
interface NavigationProgressProps extends ElementProps<'div'> {
71
  store?: NprogressStore;
72
  initialProgress?: number;
73
  color?: MantineColor;
74
  size?: number;
75
  stepInterval?: number;
76
  withinPortal?: boolean;
77
  portalProps?: Omit<BasePortalProps, 'withinPortal'>;
78
  zIndex?: React.CSSProperties['zIndex'];
79
}
80
```
81

82
[NavigationProgress Component](./navigation-progress-component.md)
83

84
### Progress State Management
85

86
Core store system providing state management for progress tracking, with hooks for React integration and state subscription.
87

88
```typescript { .api }
89
type NprogressStore = MantineStore<NprogressState>;
90

91
interface NprogressState {
92
  mounted: boolean;
93
  progress: number;
94
  interval: number;
95
  step: number;
96
  stepInterval: number;
97
  timeouts: number[];
98
}
99

100
function createNprogressStore(): NprogressStore;
101
function useNprogress(store: NprogressStore): NprogressState;
102
```
103

104
[Progress State Management](./progress-state-management.md)
105

106
### Imperative Progress Control
107

108
Action functions for programmatic control of progress state, enabling integration with routing libraries and custom navigation flows.
109

110
```typescript { .api }
111
function startNavigationProgress(): void;
112
function stopNavigationProgress(): void;
113
function setNavigationProgress(value: number): void;
114
function incrementNavigationProgress(): void;
115
function decrementNavigationProgress(): void;
116
function completeNavigationProgress(): void;
117
function resetNavigationProgress(): void;
118
function cleanupNavigationProgress(): void;
119
```
120

121
[Imperative Progress Control](./imperative-progress-control.md)
122

123
### Custom Store Creation
124

125
Factory functions for creating isolated progress store instances, useful for multiple independent progress bars or complex applications.
126

127
```typescript { .api }
128
function createNprogress(): readonly [NprogressStore, ActionsObject];
129

130
interface ActionsObject {
131
  start(): void;
132
  stop(): void;
133
  reset(): void;
134
  set(value: number): void;
135
  increment(): void;
136
  decrement(): void;
137
  complete(): void;
138
  cleanup(): void;
139
}
140
```
141

142
[Custom Store Creation](./custom-store-creation.md)
143

144
## Global Types
145

146
```typescript { .api }
147
type MantineColor = string;
148

149
interface ElementProps<T extends keyof HTMLElementTagNameMap> 
150
  extends React.ComponentPropsWithoutRef<T> {}
151

152
interface BasePortalProps {
153
  withinPortal?: boolean;
154
  target?: HTMLElement | string;
155
  children: React.ReactNode;
156
}
157
```