diff --git a/README.md b/README.md index ab6744a..cb4f526 100644 --- a/README.md +++ b/README.md @@ -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 `` in your ``. Now you can use the component: ```jsx const percentage = 66; -; + ``` ## 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'; - -; -``` - -`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 ``` -However, you're not limited to the CSS properties shown above—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 `` 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)