0
# Core Progress Display
1

2
The primary CircularProgressbar component provides SVG-based circular progress visualization with extensive customization options for displaying progress values.
3

4
## Capabilities
5

6
### CircularProgressbar Component
7

8
Main component for rendering circular progress indicators with full customization control.
9

10
```typescript { .api }
11
/**
12
 * Primary circular progressbar component with extensive customization options
13
 * @param props - Component props including value, styling, and behavior options
14
 * @returns React component rendering SVG-based circular progressbar
15
 */
16
class CircularProgressbar extends React.Component<CircularProgressbarProps>;
17

18
interface CircularProgressbarDefaultProps {
19
  /** Whether to display background circle */
20
  background: boolean;
21
  /** Padding between background and path relative to total width */
22
  backgroundPadding: number;
23
  /** Ratio of full circle diameter to use (0-1) */
24
  circleRatio: number;
25
  /** CSS class names for SVG subcomponents */
26
  classes: {
27
    root: string;
28
    trail: string;
29
    path: string;
30
    text: string;
31
    background: string;
32
  };
33
  /** CSS classes to apply to the SVG element */
34
  className: string;
35
  /** Whether to rotate progressbar counterclockwise */
36
  counterClockwise: boolean;
37
  /** Maximum value for progress range */
38
  maxValue: number;
39
  /** Minimum value for progress range */
40
  minValue: number;
41
  /** Width of circular line relative to total width (0-100) */
42
  strokeWidth: number;
43
  /** Inline styles for SVG subcomponents */
44
  styles: CircularProgressbarStyles;
45
  /** Text to display inside the progressbar */
46
  text: string;
47
}
48

49
interface CircularProgressbarProps extends CircularProgressbarDefaultProps {
50
  /** Current progress value (required) */
51
  value: number;
52
}
53

54
interface CircularProgressbarWrapperProps {
55
  /** Current progress value (required) */
56
  value: number;
57
  /** Whether to display background circle */
58
  background?: boolean;
59
  /** Padding between background and path relative to total width */
60
  backgroundPadding?: number;
61
  /** Ratio of full circle diameter to use (0-1) */
62
  circleRatio?: number;
63
  /** CSS class names for SVG subcomponents */
64
  classes?: {
65
    root: string;
66
    trail: string;
67
    path: string;
68
    text: string;
69
    background: string;
70
  };
71
  /** CSS classes to apply to the SVG element */
72
  className?: string;
73
  /** Whether to rotate progressbar counterclockwise */
74
  counterClockwise?: boolean;
75
  /** Maximum value for progress range */
76
  maxValue?: number;
77
  /** Minimum value for progress range */
78
  minValue?: number;
79
  /** Width of circular line relative to total width (0-100) */
80
  strokeWidth?: number;
81
  /** Inline styles for SVG subcomponents */
82
  styles?: CircularProgressbarStyles;
83
  /** Text to display inside the progressbar */
84
  text?: string;
85
}
86

87
interface CircularProgressbarStyles {
88
  /** Styles for root SVG element */
89
  root?: React.CSSProperties;
90
  /** Styles for background trail path */
91
  trail?: React.CSSProperties;
92
  /** Styles for progress path */
93
  path?: React.CSSProperties;
94
  /** Styles for text element */
95
  text?: React.CSSProperties;
96
  /** Styles for background circle */
97
  background?: React.CSSProperties;
98
}
99
```
100

101
**Default Values:**
102

103
The component comes with the following default values (defined in `CircularProgressbarDefaultProps`):
104

105
```typescript { .api }
106
const defaultProps: CircularProgressbarDefaultProps = {
107
  background: false,
108
  backgroundPadding: 0,
109
  circleRatio: 1,
110
  classes: {
111
    root: 'CircularProgressbar',
112
    trail: 'CircularProgressbar-trail',
113
    path: 'CircularProgressbar-path',
114
    text: 'CircularProgressbar-text',
115
    background: 'CircularProgressbar-background',
116
  },
117
  className: '',
118
  counterClockwise: false,
119
  maxValue: 100,
120
  minValue: 0,
121
  strokeWidth: 8,
122
  styles: {
123
    root: {},
124
    trail: {},
125
    path: {},
126
    text: {},
127
    background: {},
128
  },
129
  text: '',
130
};
131
```
132

133
**Usage Examples:**
134

135
```tsx
136
import React from 'react';
137
import { CircularProgressbar } from 'react-circular-progressbar';
138
import 'react-circular-progressbar/dist/styles.css';
139

140
// Basic usage with percentage
141
function BasicProgress() {
142
  return (
143
    <div style={{ width: 100, height: 100 }}>
144
      <CircularProgressbar value={66} text="66%" />
145
    </div>
146
  );
147
}
148

149
// Custom value range
150
function CustomRange() {
151
  const score = 850;
152
  const maxScore = 1000;
153
  
154
  return (
155
    <div style={{ width: 150, height: 150 }}>
156
      <CircularProgressbar 
157
        value={score} 
158
        maxValue={maxScore}
159
        text={`${score}/${maxScore}`} 
160
      />
161
    </div>
162
  );
163
}
164

165
// With background and custom stroke width
166
function StyledProgress() {
167
  return (
168
    <div style={{ width: 200, height: 200 }}>
169
      <CircularProgressbar
170
        value={75}
171
        text="75%"
172
        background={true}
173
        backgroundPadding={6}
174
        strokeWidth={12}
175
      />
176
    </div>
177
  );
178
}
179

180
// Partial circle (semi-circle)
181
function SemiCircle() {
182
  return (
183
    <div style={{ width: 200, height: 100 }}>
184
      <CircularProgressbar
185
        value={80}
186
        text="80%"
187
        circleRatio={0.5}
188
        styles={{
189
          root: { transform: 'rotate(0.25turn)' },
190
          path: { transformOrigin: 'center center' },
191
          trail: { transformOrigin: 'center center' }
192
        }}
193
      />
194
    </div>
195
  );
196
}
197
```
198

199
### Custom CSS Classes
200

201
Override default CSS class names for complete styling control.
202

203
```typescript { .api }
204
/**
205
 * CSS class name overrides for SVG subcomponents
206
 */
207
interface CircularProgressbarClasses {
208
  /** Class name for root SVG element. Default: 'CircularProgressbar' */
209
  root: string;
210
  /** Class name for background trail path. Default: 'CircularProgressbar-trail' */
211
  trail: string;
212
  /** Class name for progress path. Default: 'CircularProgressbar-path' */
213
  path: string;
214
  /** Class name for text element. Default: 'CircularProgressbar-text' */
215
  text: string;
216
  /** Class name for background circle. Default: 'CircularProgressbar-background' */
217
  background: string;
218
}
219
```
220

221
**Usage Example:**
222

223
```tsx
224
// Custom CSS classes for integration with CSS-in-JS libraries
225
function CustomClasses() {
226
  return (
227
    <CircularProgressbar
228
      value={60}
229
      text="60%"
230
      classes={{
231
        root: 'my-progress-root',
232
        trail: 'my-progress-trail',
233
        path: 'my-progress-path',
234
        text: 'my-progress-text',
235
        background: 'my-progress-bg'
236
      }}
237
    />
238
  );
239
}
240
```
241

242
### Inline Styling
243

244
Direct style control through the styles prop for fine-grained customization.
245

246
```typescript { .api }
247
/**
248
 * Inline style overrides for SVG subcomponents
249
 */
250
interface CircularProgressbarStyles {
251
  /** Styles applied to root SVG element */
252
  root?: React.CSSProperties;
253
  /** Styles applied to background trail path */
254
  trail?: React.CSSProperties;
255
  /** Styles applied to progress path */
256
  path?: React.CSSProperties;
257
  /** Styles applied to text element */
258
  text?: React.CSSProperties;
259
  /** Styles applied to background circle */
260
  background?: React.CSSProperties;
261
}
262
```
263

264
**Usage Example:**
265

266
```tsx
267
// Direct inline styling
268
function InlineStyles() {
269
  return (
270
    <CircularProgressbar
271
      value={45}
272
      text="45%"
273
      styles={{
274
        root: {
275
          filter: 'drop-shadow(3px 3px 6px rgba(0,0,0,0.1))'
276
        },
277
        path: {
278
          stroke: '#f88',
279
          strokeLinecap: 'round',
280
          transition: 'stroke-dashoffset 0.5s ease 0s'
281
        },
282
        trail: {
283
          stroke: '#d6d6d6',
284
          strokeLinecap: 'round'
285
        },
286
        text: {
287
          fill: '#f88',
288
          fontSize: '16px',
289
          fontWeight: 'bold'
290
        },
291
        background: {
292
          fill: '#3e98c7',
293
          opacity: 0.1
294
        }
295
      }}
296
    />
297
  );
298
}
299
```