0
# NavigationProgress Component
1

2
The NavigationProgress component renders a visual progress bar that can be controlled through props or external state management. It provides full customization options for appearance, behavior, and rendering location.
3

4
## Capabilities
5

6
### NavigationProgress Function
7

8
Main React component for rendering the navigation progress bar.
9

10
```typescript { .api }
11
/**
12
 * Navigation progress bar component that displays loading progress
13
 * @param props - Component props including store, appearance, and behavior options
14
 * @returns JSX.Element rendered through OptionalPortal
15
 */
16
function NavigationProgress(props: NavigationProgressProps): JSX.Element;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { NavigationProgress } from "@mantine/nprogress";
23
import "@mantine/nprogress/styles.css";
24

25
// Basic usage with default settings
26
function App() {
27
  return <NavigationProgress />;
28
}
29

30
// Customized appearance
31
function CustomApp() {
32
  return (
33
    <NavigationProgress
34
      color="blue"
35
      size={5}
36
      stepInterval={300}
37
      initialProgress={10}
38
    />
39
  );
40
}
41

42
// Using custom store
43
import { createNprogressStore } from "@mantine/nprogress";
44

45
const customStore = createNprogressStore();
46

47
function IsolatedProgress() {
48
  return <NavigationProgress store={customStore} />;
49
}
50
```
51

52
### NavigationProgressProps Interface
53

54
Complete props interface for the NavigationProgress component.
55

56
```typescript { .api }
57
interface NavigationProgressProps extends ElementProps<'div'> {
58
  /** Component store, controls state. Uses default nprogressStore if not provided */
59
  store?: NprogressStore;
60
  
61
  /** Initial progress value. @default 0 */
62
  initialProgress?: number;
63
  
64
  /** Key of theme.colors or any valid CSS color. @default theme.primaryColor */
65
  color?: MantineColor;
66
  
67
  /** Controls height of the progress bar in pixels */
68
  size?: number;
69
  
70
  /** Step interval in milliseconds for automatic progress increments. Component default: 500ms, store default: 100ms. @default 500 */
71
  stepInterval?: number;
72
  
73
  /** Determines whether the progress bar should be rendered within Portal. @default true */
74
  withinPortal?: boolean;
75
  
76
  /** Props to pass down to the Portal when withinPortal is true */
77
  portalProps?: Omit<BasePortalProps, 'withinPortal'>;
78
  
79
  /** Progress bar z-index for layering control. @default 9999 */
80
  zIndex?: React.CSSProperties['zIndex'];
81
}
82
```
83

84
### Component Properties
85

86
Static properties available on the NavigationProgress component.
87

88
```typescript { .api }
89
/** Display name for React DevTools */
90
NavigationProgress.displayName: "@mantine/nprogress/NavigationProgress";
91
```
92

93
### Portal Rendering Control
94

95
The component supports both portal-based and inline rendering for flexible z-index management.
96

97
**Portal Rendering (default):**
98
```typescript
99
// Renders at document.body level with high z-index
100
<NavigationProgress withinPortal={true} zIndex={10000} />
101

102
// Custom portal target
103
<NavigationProgress 
104
  withinPortal={true}
105
  portalProps={{ target: document.getElementById('custom-root') }}
106
/>
107
```
108

109
**Inline Rendering:**
110
```typescript
111
// Renders as direct child with normal stacking context
112
<NavigationProgress withinPortal={false} />
113
```
114

115
### Color Configuration
116

117
Supports both theme-based and custom CSS colors.
118

119
```typescript
120
// Theme colors
121
<NavigationProgress color="blue" />
122
<NavigationProgress color="red" />
123

124
// Custom CSS colors
125
<NavigationProgress color="#ff6b6b" />
126
<NavigationProgress color="rgb(255, 107, 107)" />
127
<NavigationProgress color="hsl(0, 100%, 71%)" />
128
```
129

130
## Types
131

132
```typescript { .api }
133
interface ElementProps<T extends keyof HTMLElementTagNameMap> 
134
  extends React.ComponentPropsWithoutRef<T> {}
135

136
interface BasePortalProps {
137
  withinPortal?: boolean;
138
  target?: HTMLElement | string;
139
  children: React.ReactNode;
140
}
141

142
type MantineColor = string;
143
type NprogressStore = MantineStore<NprogressState>;
144
```