0
# React Circular Progressbar
1

2
React Circular Progressbar is a highly customizable circular progress indicator component built with React and SVG. It offers extensive theming capabilities through CSS and inline styles, supports arbitrary content placement within the progressbar, and provides features like custom value ranges, rotation options, stroke width customization, and animation controls.
3

4
## Package Information
5

6
- **Package Name**: react-circular-progressbar
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-circular-progressbar`
10

11
## Core Imports
12

13
```typescript
14
import { CircularProgressbar } from 'react-circular-progressbar';
15
import 'react-circular-progressbar/dist/styles.css';
16
```
17

18
With children support:
19

20
```typescript
21
import { CircularProgressbarWithChildren } from 'react-circular-progressbar';
22
import 'react-circular-progressbar/dist/styles.css';
23
```
24

25
For style customization:
26

27
```typescript
28
import { CircularProgressbar, buildStyles } from 'react-circular-progressbar';
29
import 'react-circular-progressbar/dist/styles.css';
30
```
31

32
## Basic Usage
33

34
```tsx
35
import React from 'react';
36
import { CircularProgressbar } from 'react-circular-progressbar';
37
import 'react-circular-progressbar/dist/styles.css';
38

39
function App() {
40
  const percentage = 66;
41
  
42
  return (
43
    <div style={{ width: 200, height: 200 }}>
44
      <CircularProgressbar value={percentage} text={`${percentage}%`} />
45
    </div>
46
  );
47
}
48
```
49

50
## Architecture
51

52
React Circular Progressbar is built around several key components:
53

54
- **CircularProgressbar**: Core component rendering SVG-based circular progress indicator
55
- **CircularProgressbarWithChildren**: Wrapper component enabling arbitrary content placement inside the progressbar
56
- **buildStyles**: Utility function for generating style objects with common customization options
57
- **SVG Path System**: Internal Path component handling circular path rendering with customizable dash patterns
58
- **Style System**: Comprehensive styling through CSS classes and inline styles with full customization of all visual elements
59

60
**Type System Architecture:**
61

62
The component's type system is designed around inheritance for flexibility:
63

64
- **CircularProgressbarDefaultProps**: Defines all default values that the component provides (all required)
65
- **CircularProgressbarProps**: Extends default props and adds the required `value` property
66
- **CircularProgressbarWrapperProps**: Defines optional props for wrapper components (all optional except `value`)
67
- **CircularProgressbarWithChildrenProps**: Extends wrapper props and adds optional `children` property
68

69
This design allows the main component to have comprehensive defaults while wrapper components remain flexible.
70

71
## Capabilities
72

73
### Core Progress Display
74

75
Primary circular progressbar component with extensive customization options for displaying progress values from 0-100 or custom ranges.
76

77
```typescript { .api }
78
interface CircularProgressbarProps extends CircularProgressbarDefaultProps {
79
  value: number;
80
}
81

82
interface CircularProgressbarDefaultProps {
83
  background: boolean;
84
  backgroundPadding: number;
85
  circleRatio: number;
86
  classes: {
87
    root: string;
88
    trail: string;
89
    path: string;
90
    text: string;
91
    background: string;
92
  };
93
  className: string;
94
  counterClockwise: boolean;
95
  maxValue: number;
96
  minValue: number;
97
  strokeWidth: number;
98
  styles: CircularProgressbarStyles;
99
  text: string;
100
}
101

102
interface CircularProgressbarStyles {
103
  root?: React.CSSProperties;
104
  trail?: React.CSSProperties;
105
  path?: React.CSSProperties;
106
  text?: React.CSSProperties;
107
  background?: React.CSSProperties;
108
}
109
```
110

111
[Core Progressbar](./core-progressbar.md)
112

113
### Content Integration
114

115
Wrapper component that allows placing arbitrary JSX content inside the progressbar with automatic centering and responsive sizing.
116

117
```typescript { .api }
118
interface CircularProgressbarWithChildrenProps extends CircularProgressbarWrapperProps {
119
  children?: React.ReactNode;
120
}
121

122
interface CircularProgressbarWrapperProps {
123
  value: number;
124
  background?: boolean;
125
  backgroundPadding?: number;
126
  circleRatio?: number;
127
  classes?: {
128
    root: string;
129
    trail: string;
130
    path: string;
131
    text: string;
132
    background: string;
133
  };
134
  className?: string;
135
  counterClockwise?: boolean;
136
  maxValue?: number;
137
  minValue?: number;
138
  strokeWidth?: number;
139
  styles?: CircularProgressbarStyles;
140
  text?: string;
141
}
142
```
143

144
[Content Integration](./content-integration.md)
145

146
### Style Customization
147

148
Utility function for generating comprehensive style objects with common customization options like colors, transitions, and rotations.
149

150
```typescript { .api }
151
function buildStyles(options: {
152
  rotation?: number;
153
  strokeLinecap?: any;
154
  textColor?: string;
155
  textSize?: string | number;
156
  pathColor?: string;
157
  pathTransition?: string;
158
  pathTransitionDuration?: number;
159
  trailColor?: string;
160
  backgroundColor?: string;
161
}): CircularProgressbarStyles;
162
```
163

164
[Style Customization](./style-customization.md)