0
# rc-progress
1

2
rc-progress is a React component library providing customizable Line and Circle progress bars with advanced features including gradients, multi-segment progress, step visualization, and responsive SVG rendering.
3

4
## Package Information
5

6
- **Package Name**: rc-progress
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install rc-progress`
10
- **Dependencies**: classnames, rc-util, @babel/runtime
11
- **Peer Dependencies**: react (>=16.9.0), react-dom (>=16.9.0)
12

13
## Core Imports
14

15
```typescript
16
import { Line, Circle } from "rc-progress";
17
import type { ProgressProps } from "rc-progress";
18
```
19

20
For CommonJS:
21

22
```javascript
23
const { Line, Circle } = require("rc-progress");
24
```
25

26
Default import (provides object with Line and Circle):
27

28
```typescript
29
import Progress from "rc-progress";
30
// Usage: Progress.Line, Progress.Circle
31
// Progress is equivalent to { Line, Circle }
32
```
33

34
## Basic Usage
35

36
```typescript
37
import React from "react";
38
import { Line, Circle } from "rc-progress";
39

40
export default function MyComponent() {
41
  return (
42
    <div>
43
      {/* Basic line progress bar */}
44
      <Line percent={75} strokeWidth={4} strokeColor="#2db7f5" />
45
      
46
      {/* Basic circle progress bar */}
47
      <Circle percent={75} strokeWidth={6} strokeColor="#2db7f5" />
48
      
49
      {/* Multi-segment progress */}
50
      <Line 
51
        percent={[30, 20, 25]} 
52
        strokeColor={["#108ee9", "#87d068", "#ff6b6b"]} 
53
      />
54
      
55
      {/* Circle with gradient */}
56
      <Circle 
57
        percent={80}
58
        strokeWidth={8}
59
        strokeColor={{
60
          "0%": "#108ee9",
61
          "100%": "#87d068"
62
        }}
63
      />
64
    </div>
65
  );
66
}
67
```
68

69
## Capabilities
70

71
### Line Progress Component
72

73
Linear progress bar component using SVG paths for scalable rendering.
74

75
```typescript { .api }
76
/**
77
 * Linear progress bar component
78
 */
79
const Line: React.FC<ProgressProps>;
80
```
81

82
### Circle Progress Component
83

84
Circular progress bar component with advanced features like gaps, gradients, and step visualization.
85

86
```typescript { .api }
87
/**
88
 * Circular progress bar component with advanced customization
89
 */
90
const Circle: React.FC<ProgressProps>;
91
```
92

93
### Progress Properties Interface
94

95
Core interface defining all available props for both Line and Circle components.
96

97
```typescript { .api }
98
interface ProgressProps {
99
  /** Unique identifier for the progress component */
100
  id?: string;
101
  /** Width of the progress stroke as percentage of SVG canvas size */
102
  strokeWidth?: number;
103
  /** Width of the trail stroke, defaults to strokeWidth if not specified */
104
  trailWidth?: number;
105
  /** CSS class name for styling */
106
  className?: string;
107
  /** Progress percentage(s) - supports single value or array for multi-segment */
108
  percent?: number | number[];
109
  /** Color(s) of the progress stroke - supports strings, gradients, and arrays */
110
  strokeColor?: StrokeColorType;
111
  /** Color of the background trail */
112
  trailColor?: string;
113
  /** Shape of stroke line endings */
114
  strokeLinecap?: StrokeLinecapType;
115
  /** CSS class prefix for internal elements */
116
  prefixCls?: string;
117
  /** Inline CSS styles applied to SVG element */
118
  style?: React.CSSProperties;
119
  /** Gap degree for circle component (0-360) */
120
  gapDegree?: number;
121
  /** Position of gap in circle component */
122
  gapPosition?: GapPositionType;
123
  /** CSS transition property for animations */
124
  transition?: string;
125
  /** Click event handler */
126
  onClick?: React.MouseEventHandler;
127
  /** Step configuration for discrete progress visualization */
128
  steps?: number | { count: number; gap: number };
129
}
130
```
131

132
### Multi-Segment Progress
133

134
Both Line and Circle components support multi-segment progress by passing arrays to `percent` and `strokeColor` properties.
135

136
```typescript
137
// Multi-segment example
138
<Line 
139
  percent={[25, 35, 15]} 
140
  strokeColor={["#ff4d4f", "#52c41a", "#1890ff"]}
141
/>
142

143
// Stacked segments add up to total progress
144
<Circle 
145
  percent={[40, 30]} 
146
  strokeColor={["#ff7875", "#73d13d"]}
147
/>
148
```
149

150
### Gradient Support
151

152
Circle component supports linear and conic gradients using color objects.
153

154
```typescript
155
// Linear gradient
156
<Circle 
157
  strokeColor={{
158
    "0%": "#108ee9",
159
    "50%": "#87d068", 
160
    "100%": "#ff6b6b"
161
  }}
162
/>
163

164
// Conic gradient - set conic: true for circular gradients
165
<Circle 
166
  percent={100}
167
  strokeColor={{
168
    conic: true,
169
    "0%": "#ff0000",
170
    "33%": "#00ff00",
171
    "66%": "#0000ff",
172
    "100%": "#ff0000"
173
  }}
174
/>
175
```
176

177
### Step Visualization
178

179
Circle component supports discrete step visualization for progress indicators.
180

181
```typescript
182
// Simple step count
183
<Circle steps={5} percent={60} />
184

185
// Steps with spacing
186
<Circle 
187
  steps={{ count: 8, gap: 2 }} 
188
  percent={75}
189
  strokeColor="#1890ff"
190
/>
191
```
192

193
### Gap Configuration
194

195
Circle component supports customizable gaps for partial circle progress.
196

197
```typescript
198
// 90-degree gap at bottom
199
<Circle 
200
  gapDegree={90}
201
  gapPosition="bottom"
202
  percent={75}
203
/>
204

205
// Available positions: 'top', 'right', 'bottom', 'left'
206
<Circle 
207
  gapDegree={120}
208
  gapPosition="top"
209
  percent={50}
210
/>
211
```
212

213
## Types
214

215
### Stroke Color Types
216

217
```typescript { .api }
218
/** Color object for gradients with percentage keys and optional conic flag */
219
type StrokeColorObject = Record<string, string> & { conic?: boolean };
220

221
/** Basic stroke color - string or gradient object */
222
type BaseStrokeColorType = string | StrokeColorObject;
223

224
/** Stroke color supporting arrays for multi-segment progress */
225
type StrokeColorType = BaseStrokeColorType | BaseStrokeColorType[];
226
```
227

228
### Position and Style Types
229

230
```typescript { .api }
231
/** Available gap positions for circle component */
232
type GapPositionType = 'top' | 'right' | 'bottom' | 'left';
233

234
/** SVG line cap styles */
235
type StrokeLinecapType = 'round' | 'butt' | 'square';
236
```
237

238
## Default Values
239

240
The components use the following default values:
241

242
```typescript { .api }
243
const defaultProps: Partial<ProgressProps> = {
244
  percent: 0,
245
  prefixCls: 'rc-progress',
246
  strokeColor: '#2db7f5',
247
  strokeLinecap: 'round',
248
  strokeWidth: 1,
249
  trailColor: '#D9D9D9',
250
  trailWidth: 1,
251
  gapPosition: 'bottom',
252
};
253
```
254

255
## Advanced Usage Examples
256

257
### Animated Progress Updates
258

259
```typescript
260
import React, { useState, useEffect } from "react";
261
import { Line, Circle } from "rc-progress";
262

263
function AnimatedProgress() {
264
  const [percent, setPercent] = useState(0);
265
  
266
  useEffect(() => {
267
    const timer = setInterval(() => {
268
      setPercent(prev => prev >= 100 ? 0 : prev + 1);
269
    }, 100);
270
    return () => clearInterval(timer);
271
  }, []);
272
  
273
  return (
274
    <div>
275
      <Line percent={percent} strokeWidth={4} />
276
      <Circle percent={percent} strokeWidth={6} />
277
    </div>
278
  );
279
}
280
```
281

282
### Custom Styling and Events
283

284
```typescript
285
import React from "react";
286
import { Circle } from "rc-progress";
287

288
function InteractiveProgress() {
289
  const handleClick = (event: React.MouseEvent) => {
290
    console.log("Progress clicked!", event);
291
  };
292
  
293
  return (
294
    <Circle
295
      percent={85}
296
      strokeWidth={10}
297
      strokeColor="#52c41a"
298
      trailColor="#f0f0f0"
299
      className="my-progress"
300
      style={{ width: 200, height: 200 }}
301
      onClick={handleClick}
302
    />
303
  );
304
}
305
```
306

307
### Multi-Color Segments
308

309
```typescript
310
import React from "react";
311
import { Line } from "rc-progress";
312

313
function SegmentedProgress() {
314
  return (
315
    <Line
316
      percent={[20, 30, 25, 15]}
317
      strokeWidth={8}
318
      strokeColor={[
319
        "#ff4d4f", // Red segment
320
        "#faad14", // Orange segment  
321
        "#52c41a", // Green segment
322
        "#1890ff"  // Blue segment
323
      ]}
324
      strokeLinecap="round"
325
    />
326
  );
327
}
328
```
329

330
## Browser Compatibility
331

332
- IE11, Edge, Chrome (last 2 versions), Firefox (last 2 versions), Safari (last 2 versions), Electron (last 2 versions)
333
- Modern React applications (16.9.0+) 
334
- SVG-based rendering for consistent cross-browser support