0
# Radix UI React Progress
1

2
A React progress component that provides an accessible way to display the completion progress of a task, typically displayed as a progress bar. Part of the Radix UI Primitives collection, it offers compound component architecture with Progress as the root container and ProgressIndicator for displaying the visual progress representation.
3

4
## Package Information
5

6
- **Package Name**: @radix-ui/react-progress
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @radix-ui/react-progress`
10

11
## Core Imports
12

13
```typescript
14
import { Progress, ProgressIndicator } from "@radix-ui/react-progress";
15
```
16

17
Import with types:
18

19
```typescript
20
import { 
21
  Progress, 
22
  ProgressIndicator, 
23
  type ProgressProps, 
24
  type ProgressIndicatorProps 
25
} from "@radix-ui/react-progress";
26
```
27

28
Import with context scope creation:
29

30
```typescript
31
import { 
32
  Progress, 
33
  ProgressIndicator, 
34
  createProgressScope 
35
} from "@radix-ui/react-progress";
36
```
37

38
Alternative component name imports:
39

40
```typescript
41
import { Root, Indicator } from "@radix-ui/react-progress";
42
```
43

44
For CommonJS:
45

46
```javascript
47
const { Progress, ProgressIndicator } = require("@radix-ui/react-progress");
48
```
49

50
**Note**: This package includes a `'use client'` directive for Next.js App Router compatibility.
51

52
## Basic Usage
53

54
```typescript
55
import * as React from "react";
56
import { Progress, ProgressIndicator } from "@radix-ui/react-progress";
57

58
// Determinate progress (specific value)
59
function App() {
60
  const [progress, setProgress] = React.useState(65);
61

62
  return (
63
    <Progress value={progress} max={100} className="progress-root">
64
      <ProgressIndicator 
65
        className="progress-indicator" 
66
        style={{ transform: `translateX(-${100 - progress}%)` }}
67
      />
68
    </Progress>
69
  );
70
}
71

72
// Indeterminate progress (loading state)
73
function LoadingProgress() {
74
  return (
75
    <Progress className="progress-root">
76
      <ProgressIndicator className="progress-indicator loading" />
77
    </Progress>
78
  );
79
}
80
```
81

82
## Architecture
83

84
The Progress component follows Radix UI's compound component pattern:
85

86
- **Progress (Root)**: Container component that manages state and accessibility attributes
87
- **ProgressIndicator**: Visual component that displays the progress representation
88
- **Context-based Communication**: Components share state through React context
89
- **Accessibility-first**: Built-in ARIA attributes and screen reader support
90
- **Styling Flexibility**: Unstyled components that accept className and style props
91

92
## Capabilities
93

94
### Progress Root Component
95

96
The main container component that provides context and accessibility attributes for the progress indicator.
97

98
```typescript { .api }
99
interface ProgressProps extends React.ComponentPropsWithoutRef<'div'> {
100
  /** The progress value. Use `null` or `undefined` for indeterminate progress */
101
  value?: number | null | undefined;
102
  /** The maximum progress value. Defaults to 100 */
103
  max?: number;
104
  /** Custom function to generate value label for accessibility. Defaults to percentage calculation */
105
  getValueLabel?(value: number, max: number): string;
106
}
107

108
declare const Progress: React.ForwardRefExoticComponent<
109
  ProgressProps & React.RefAttributes<HTMLDivElement>
110
>;
111
```
112

113
**Progress States:**
114
- **loading**: Progress value between 0 and max (excluding max)
115
- **complete**: Progress value equals max value
116
- **indeterminate**: No value provided (null or undefined)
117

118
**Data Attributes:**
119
- `data-state`: Current progress state ('loading' | 'complete' | 'indeterminate')
120
- `data-value`: Current progress value (when not indeterminate)
121
- `data-max`: Maximum progress value
122

123
**ARIA Attributes:**
124
- `role="progressbar"`
125
- `aria-valuemin="0"`
126
- `aria-valuemax`: Set to max prop value
127
- `aria-valuenow`: Current progress value (when not indeterminate)
128
- `aria-valuetext`: Generated value label for accessibility
129

130
### Progress Indicator Component
131

132
Visual component that displays the actual progress representation and inherits state from the Progress context.
133

134
```typescript { .api }
135
interface ProgressIndicatorProps extends React.ComponentPropsWithoutRef<'div'> {}
136

137
declare const ProgressIndicator: React.ForwardRefExoticComponent<
138
  ProgressIndicatorProps & React.RefAttributes<HTMLDivElement>
139
>;
140
```
141

142
The ProgressIndicator automatically receives the same data attributes as the Progress component:
143
- `data-state`: Inherited progress state
144
- `data-value`: Inherited progress value
145
- `data-max`: Inherited maximum value
146

147
### Component Aliases
148

149
```typescript { .api }
150
/** Alias for Progress component */
151
declare const Root: typeof Progress;
152

153
/** Alias for ProgressIndicator component */
154
declare const Indicator: typeof ProgressIndicator;
155
```
156

157
### Context Scope Creation
158

159
For advanced use cases requiring multiple Progress components with isolated contexts.
160

161
```typescript { .api }
162
/**
163
 * Creates a scoped context for Progress components
164
 * @returns Scope creation function for isolated Progress contexts
165
 */
166
declare function createProgressScope(): CreateScope;
167

168
/** Create scope function interface */
169
interface CreateScope {
170
  scopeName: string;
171
  (): ScopeHook;
172
}
173

174
/** Scope hook type returned by createProgressScope */
175
type ScopeHook = (scope: Scope) => { [__scopeProp: string]: Scope };
176

177
/** Scope type for context isolation */
178
type Scope<C = any> = { [scopeName: string]: React.Context<C>[] } | undefined;
179
```
180

181
## Types
182

183
```typescript { .api }
184
/** Props interface for Progress component */
185
interface ProgressProps extends React.ComponentPropsWithoutRef<'div'> {
186
  value?: number | null | undefined;
187
  max?: number;
188
  getValueLabel?(value: number, max: number): string;
189
}
190

191
/** Props interface for ProgressIndicator component */
192
interface ProgressIndicatorProps extends React.ComponentPropsWithoutRef<'div'> {}
193

194
/** Internal progress state representation */
195
type ProgressState = 'indeterminate' | 'complete' | 'loading';
196

197
/** Element type for Progress component */
198
type ProgressElement = React.ComponentRef<'div'>;
199

200
/** Element type for ProgressIndicator component */
201
type ProgressIndicatorElement = React.ComponentRef<'div'>;
202
```
203

204
## Validation and Error Handling
205

206
The Progress component includes built-in validation with console warnings:
207

208
- **Invalid max value**: Must be a positive number greater than 0. Defaults to 100 if invalid.
209
- **Invalid progress value**: Must be between 0 and max (inclusive) or null/undefined for indeterminate state. Defaults to null if invalid.
210
- **Default value label**: When no `getValueLabel` function is provided, defaults to percentage calculation (e.g., "65%" for value 65 of max 100).
211

212
## Usage Examples
213

214
**File Upload Progress:**
215

216
```typescript
217
function FileUploadProgress({ uploadProgress }: { uploadProgress: number | null }) {
218
  return (
219
    <Progress 
220
      value={uploadProgress} 
221
      max={100}
222
      getValueLabel={(value, max) => `${value} of ${max} percent uploaded`}
223
    >
224
      <ProgressIndicator 
225
        style={{ 
226
          transform: uploadProgress ? `translateX(-${100 - uploadProgress}%)` : 'translateX(-100%)',
227
          transition: 'transform 0.3s ease'
228
        }}
229
      />
230
    </Progress>
231
  );
232
}
233
```
234

235
**Multi-step Form Progress:**
236

237
```typescript
238
function FormProgress({ currentStep, totalSteps }: { currentStep: number; totalSteps: number }) {
239
  const progress = (currentStep / totalSteps) * 100;
240
  
241
  return (
242
    <Progress 
243
      value={progress} 
244
      max={100}
245
      getValueLabel={(value) => `Step ${currentStep} of ${totalSteps}`}
246
    >
247
      <ProgressIndicator 
248
        style={{ width: `${progress}%` }}
249
      />
250
    </Progress>
251
  );
252
}
253
```
254

255
**Loading State with Animation:**
256

257
```typescript
258
function LoadingProgress() {
259
  return (
260
    <Progress className="loading-progress">
261
      <ProgressIndicator className="loading-indicator" />
262
    </Progress>
263
  );
264
}
265

266
// CSS for indeterminate animation
267
const styles = `
268
  .loading-progress {
269
    overflow: hidden;
270
  }
271
  
272
  .loading-indicator {
273
    animation: loading 2s ease-in-out infinite;
274
  }
275
  
276
  @keyframes loading {
277
    0% { transform: translateX(-100%); }
278
    50% { transform: translateX(0%); }
279
    100% { transform: translateX(100%); }
280
  }
281
`;
282
```