diff --git a/README.md b/README.md index 17b2579..7ffc3a9 100644 --- a/README.md +++ b/README.md @@ -24,47 +24,39 @@ npm install --save react-circular-progressbar ## Usage -Import the component: - -```javascript -import CircularProgressbar from 'react-circular-progressbar'; -``` - -If you have a CSS loader configured, you can import the stylesheet: +Import the component and default styles: ```javascript +import { CircularProgressbar } from 'react-circular-progressbar'; import 'react-circular-progressbar/dist/styles.css'; ``` -If not, you can copy [styles.css](src/styles.css) into your project instead, and include `` in your ``. +**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. 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`. | -| `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`. | +| `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. @@ -74,7 +66,39 @@ 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 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. +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: ```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 @@ -127,10 +161,18 @@ 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 @@ -181,25 +223,22 @@ 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)