archive-gh-me/react-circular-progressbar
1
0
Fork 0
mirror of https://github.com/kevinsqi/react-circular-progressbar.git synced 2026-01-18 15:55:06 +00:00
Code Issues Projects Releases Wiki Activity

temporarily undo README changes, which document v2 stuff that hasn't been released yet

Browse Source
This commit is contained in:
Kevin Qi 2019-05-04 16:07:40 -07:00
parent 242ecf0c73
commit 393697980f
1 changed files with 40 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

119
README.md
View File

@ -24,40 +24,48 @@ npm install --save react-circular-progressbar
## Usage
Import the component and default styles:
Import the component:
```javascript
import CircularProgressbar from 'react-circular-progressbar';
```
If you have a CSS loader configured, you can import the stylesheet:
```javascript
import { CircularProgressbar } from 'react-circular-progressbar';
import 'react-circular-progressbar/dist/styles.css';
```
**Note**: Importing CSS requires a CSS loader (if you're using create-react-app, this is already set up for you). If you don't have a CSS loader, you can copy [styles.css](src/styles.css) into your project instead.
If not, you can copy [styles.css](src/styles.css) into your project instead, and include `<link rel="stylesheet" href="styles.css" />` in your `<head>`.
Now you can use the component:
```jsx
const percentage = 66;
<CircularProgressbar percentage={percentage} text={`${percentage}%`} />;
<CircularProgressbar
percentage={percentage}
text={`${percentage}%`}
/>
```
## Props
[**Take a look at the CodeSandbox**](https://codesandbox.io/s/vymm4oln6y) for interactive examples on how to use these props.
| Name | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `percentage` | Numeric percentage to display, from 0-100. Required. |
| `className` | Classes to apply to the svg element. Default: `''`. |
| `text` | Text to display inside progressbar. Default: `null`. |
| `strokeWidth` | Width of circular line as a percentage relative to total width of component. Default: `8`. |
| `background` | Whether to display background color. Default: `false`. |
| `backgroundPadding` | Padding between background and edge of svg as a percentage relative to total width of component. Default: `null`. |
| `initialAnimation` | Toggle whether to animate progress starting from 0% on initial mount. Default: `false`. |
| `counterClockwise` | Toggle whether to rotate progressbar in counterclockwise direction. Default: `false`. |
| `circleRatio` | Number from 0-1 representing ratio of the full circle diameter the progressbar should use. Default: `1`. |
| `classes` | Object allowing overrides of classNames of each svg subcomponent (root, trail, path, text, background). Enables styling with react-jss. See [this PR](https://github.com/kevinsqi/react-circular-progressbar/pull/25) for more detail. |
| `styles` | Object allowing customization of styles of each svg subcomponent (root, trail, path, text, background). |
| Name | Description |
| ---- | ----------- |
| `percentage` | Numeric percentage to display, from 0-100. Required. |
| `className` | Classes to apply to the svg element. Default: `''`. |
| `text` | Text to display inside progressbar. Default: `null`. |
| `strokeWidth` | Width of circular line as a percentage relative to total width of component. Default: `8`. |
| `background` | Whether to display background color. Default: `false`. |
| `backgroundPadding` | Padding between background and edge of svg as a percentage relative to total width of component. Default: `null`. |
| `initialAnimation` | Toggle whether to animate progress starting from 0% on initial mount. Default: `false`. |
| `counterClockwise` | Toggle whether to rotate progressbar in counterclockwise direction. Default: `false`. |
| `circleRatio` | Number from 0-1 representing ratio of the full circle diameter the progressbar should use. Default: `1`. |
| `classes` | Object allowing overrides of classNames of each svg subcomponent (root, trail, path, text, background). Enables styling with react-jss. See [this PR](https://github.com/kevinsqi/react-circular-progressbar/pull/25) for more detail. |
| `styles` | Object allowing customization of styles of each svg subcomponent (root, trail, path, text, background). |
Version 1.0.0 removed the `classForPercentage` and `textForPercentage` props in favor of the newer `className` and `text` props. Take a look at the [migration guide](/CHANGELOG.md) for instructions on how to migrate.
@ -67,39 +75,7 @@ Use CSS or inline styles to customize the styling - the default CSS is a good st
#### Using the `styles` prop
You can use the `styles` prop to customize each part of the progressbar (the root svg, path, trail, text, and background). This uses the native `style` prop for each subcomponent, so you can use any CSS properties here, not just the ones mentioned below.
As a convenience, you can use `buildStyles` to configure the most common style changes:
```jsx
import { CircularProgressbar, buildStyles } from 'react-circular-progressbar';
<CircularProgressbar
percentage={percentage}
text={`${percentage}%`}
styles={buildStyles({
// Rotation of path and trail, in number of turns (0-1)
rotation: 0.25,
// Whether to use rounded or flat corners on the ends - can use 'butt' or 'round'
strokeLinecap: 'butt',
// Text size
textSize: '16px',
// How long animation takes to go from one percentage to another, in seconds
pathTransitionDuration: 0.5,
// Colors
pathColor: `rgba(62, 152, 199, ${percentage / 100})`,
textColor: '#f88',
trailColor: '#d6d6d6',
backgroundColor: '#3e98c7',
})}
/>;
```
`buildStyles` transforms that into this equivalent set of CSS properties:
You can use the `styles` prop to customize the inline styles of each subcomponent of the progressbar (the root svg, path, trail, text, and background). This uses the native `style` prop for each subcomponent, so you can use any CSS properties here, not just the ones mentioned below.
```jsx
<CircularProgressbar
@ -116,19 +92,11 @@ import { CircularProgressbar, buildStyles } from 'react-circular-progressbar';
strokeLinecap: 'butt',
// Customize transition animation
transition: 'stroke-dashoffset 0.5s ease 0s',
// Rotate the path
transform: 'rotate(0.25turn)',
transformOrigin: 'center center',
},
// Customize the circle behind the path, i.e. the "total progress"
trail: {
// Trail color
stroke: '#d6d6d6',
// Whether to use rounded or flat corners on the ends - can use 'butt' or 'round'
strokeLinecap: 'butt',
// Rotate the trail
transform: 'rotate(0.25turn)',
transformOrigin: 'center center',
},
// Customize the text
text: {
@ -145,8 +113,6 @@ import { CircularProgressbar, buildStyles } from 'react-circular-progressbar';
/>
```
However, you're not limited to the CSS properties shown above&mdash;you have the full set of SVG CSS properties available to you when you use `prop.styles`.
See the [CodeSandbox examples](https://codesandbox.io/s/vymm4oln6y) for a live example on how to customize styles.
#### Using CSS
@ -162,18 +128,10 @@ import './custom.css';
```css
// custom.css
.CircularProgressbar-path {
stroke: red;
}
.CircularProgressbar-trail {
stroke: gray;
}
.CircularProgressbar-text {
fill: yellow;
}
.CircularProgressbar-background {
fill: green;
}
.CircularProgressbar-path { stroke: red; }
.CircularProgressbar-trail { stroke: gray; }
.CircularProgressbar-text { fill: yellow; }
.CircularProgressbar-background { fill: green; }
```
## Customizing the text/content inside progressbar
@ -224,22 +182,25 @@ const needDominantBaselineFix = ...
## Advanced usage
- [Delaying the animation until the progressbar is visible](https://github.com/kevinsqi/react-circular-progressbar/issues/64)
- [Using a different value range than 0-100](https://codesandbox.io/s/6z64omwv3n)
- [Rotating the progressbar by some degree](https://github.com/kevinsqi/react-circular-progressbar/issues/38)
- [Applying a gradient to the progressbar](https://github.com/kevinsqi/react-circular-progressbar/issues/31#issuecomment-338216925)
- [Customizing the background](https://github.com/kevinsqi/react-circular-progressbar/issues/21#issuecomment-336613160)
- [Creating a countdown timer](https://github.com/kevinsqi/react-circular-progressbar/issues/52)
- [Creating a dashboard/speedometer style progressbar](https://github.com/kevinsqi/react-circular-progressbar/issues/49)
* [Delaying the animation until the progressbar is visible](https://github.com/kevinsqi/react-circular-progressbar/issues/64)
* [Using a different value range than 0-100](https://codesandbox.io/s/6z64omwv3n)
* [Rotating the progressbar by some degree](https://github.com/kevinsqi/react-circular-progressbar/issues/38)
* [Applying a gradient to the progressbar](https://github.com/kevinsqi/react-circular-progressbar/issues/31#issuecomment-338216925)
* [Customizing the background](https://github.com/kevinsqi/react-circular-progressbar/issues/21#issuecomment-336613160)
* [Creating a countdown timer](https://github.com/kevinsqi/react-circular-progressbar/issues/52)
* [Creating a dashboard/speedometer style progressbar](https://github.com/kevinsqi/react-circular-progressbar/issues/49)
## Supported platforms
react-circular-progressbar does not work with React Native, because React Native does not support `<svg>` out of the box.
## Contributing
Take a look at [CONTRIBUTING.md](/CONTRIBUTING.md) to see how to help contribute to react-circular-progressbar.
## License
[MIT](/LICENSE)