A circular progress indicator
Clone or download
Latest commit c2f8fc9 Jun 28, 2018

README.md

React Circular Progressbar

npm version Build Status Bundle size

A circular progressbar component, built with SVG and extensively customizable. Try it out on CodeSandbox.

animated progressbar progressbar examples

Installation

Install with yarn:

yarn add react-circular-progressbar

or npm:

npm install --save react-circular-progressbar

Usage

Import the component:

import CircularProgressbar from 'react-circular-progressbar';

If you have a CSS loader configured, you can import the stylesheet:

import 'react-circular-progressbar/dist/styles.css';

If not, you can copy styles.css into your project instead, and include <link rel="stylesheet" href="styles.css" /> in your <head>.

Now you can use the component:

const percentage = 66;

<CircularProgressbar
  percentage={percentage}
  text={`${percentage}%`}
/>

Props

Take a look at the CodeSandbox 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.
classes Object allowing overrides of classNames of each svg subcomponent (root, trail, path, text, background). Enables styling with react-jss. See this PR 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 for instructions on how to migrate.

Customizing styles

Use CSS or inline styles to customize the styling - the default CSS is a good starting point, but you can override it as needed.

Inline style hooks

There are hooks to customize the inline styles of each subcomponent of the progressbar (the root svg, path, trail, text, and background).

<CircularProgressbar
  percentage={percentage}
  text={`${percentage}%`}
  styles={{
    path: { stroke: `rgba(62, 152, 199, ${percentage / 100})` },
    text: { fill: '#f88', fontSize: '16px' },
  }}
/>

See StyledProgressbar.js in the CodeSandbox examples for in-depth examples on how to customize these styles.

CSS hooks

There are equivalent CSS hooks for the root, path, trail, text, and background of the progressbar which you can customize.

If you're importing the default styles, you can override the defaults like this:

import 'react-circular-progressbar/dist/styles.css';
import './custom.css';
// custom.css
.CircularProgressbar-path       { stroke: red; }
.CircularProgressbar-trail      { stroke: gray; }
.CircularProgressbar-text       { fill: yellow; }
.CircularProgressbar-background { fill: green; }

Advanced usage

A lot of use cases can be covered with CSS. A few examples:

Contributing

Take a look at CONTRIBUTING.md to see how to develop on react-circular-progressbar.

License

MIT