react-circular-progressbar

What is react-circular-progressbar?

The react-circular-progressbar package is a React component library for creating customizable circular progress bars. It allows developers to easily display progress in a circular format with various customization options such as colors, text, and styles.

What are react-circular-progressbar's main functionalities?

Basic Circular Progress Bar

This feature allows you to create a basic circular progress bar. The `value` prop specifies the progress percentage.

import React from 'react';
import { CircularProgressbar } from 'react-circular-progressbar';
import 'react-circular-progressbar/dist/styles.css';

const MyComponent = () => (
  <div style={{ width: 200, height: 200 }}>
    <CircularProgressbar value={66} />
  </div>
);

export default MyComponent;

Customizable Styles

This feature allows you to customize the styles of the circular progress bar, including text color, path color, and trail color.

import React from 'react';
import { CircularProgressbar, buildStyles } from 'react-circular-progressbar';
import 'react-circular-progressbar/dist/styles.css';

const MyComponent = () => (
  <div style={{ width: 200, height: 200 }}>
    <CircularProgressbar 
      value={66} 
      styles={buildStyles({
        textColor: 'red',
        pathColor: 'turquoise',
        trailColor: 'gold'
      })}
    />
  </div>
);

export default MyComponent;

Adding Text Inside the Progress Bar

This feature allows you to add text inside the circular progress bar. The `text` prop can be used to display any text, such as the progress percentage.

import React from 'react';
import { CircularProgressbar, buildStyles } from 'react-circular-progressbar';
import 'react-circular-progressbar/dist/styles.css';

const MyComponent = () => (
  <div style={{ width: 200, height: 200 }}>
    <CircularProgressbar 
      value={66} 
      text={`${66}%`} 
      styles={buildStyles({
        textColor: 'black',
        pathColor: 'blue',
        trailColor: 'gray'
      })}
    />
  </div>
);

export default MyComponent;

Animation

This feature allows you to add animation to the circular progress bar. The `pathTransitionDuration` prop controls the duration of the animation.

import React from 'react';
import { CircularProgressbar, buildStyles } from 'react-circular-progressbar';
import 'react-circular-progressbar/dist/styles.css';

const MyComponent = () => (
  <div style={{ width: 200, height: 200 }}>
    <CircularProgressbar 
      value={66} 
      styles={buildStyles({
        pathTransitionDuration: 0.5
      })}
    />
  </div>
);

export default MyComponent;

Other packages similar to react-circular-progressbar

react-progressbar.js

react-progressbar.js is a React wrapper for ProgressBar.js, a library for creating animated progress bars. It supports both linear and circular progress bars and offers a variety of customization options. Compared to react-circular-progressbar, it provides more advanced animation capabilities and supports multiple types of progress bars.

react-sweet-progress

react-sweet-progress is a React component for creating beautiful progress bars with customizable styles and animations. It supports both linear and circular progress bars. Compared to react-circular-progressbar, it offers more visually appealing default styles and additional customization options.

react-step-progress-bar

react-step-progress-bar is a React component for creating step-based progress bars. It supports both linear and circular progress bars and allows for detailed customization of each step. Compared to react-circular-progressbar, it is more focused on step-based progress visualization and offers more granular control over each step's appearance.

README

React Circular Progressbar

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

Version 2.0.0 is out! 👋

New features:

• Use import { CircularProgressbarWithChildren } in order to put arbitrary JSX inside the component.
• Use import { buildStyles } to make it easier to customize styles.
• Use props.minValue and props.maxValue to specify a range other than 0-100.

Breaking changes: if you're upgrading from an older version, take a look at UPGRADING.md for instructions on how to migrate.

Documentation for v1.x.x will still be available at README_v1.md.

Installation

Install with yarn:

yarn add react-circular-progressbar

or npm:

npm install --save react-circular-progressbar

Usage

Import the component and default styles:

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 into your project instead.

Now you can use the component:

const percentage = 66;

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

If your values are not in percentages, you can adjust minValue and maxValue to select the scale you want:

const value = 0.66;

<CircularProgressbar value={value} maxValue={1} text={`${value * 100}%`} />;

Props

Take a look at the CodeSandbox for interactive examples on how to use these props.

ℹ️ Version 1.0.0 removed the classForPercentage and textForPercentage props in favor of className and text props. Version 2.0.0 replaces percentage with value and removes the initialAnimation prop. Take a look at UPGRADING.md for instructions on how to migrate.

Name	Description
value	Completion value of the progressbar, from minValue to maxValue. Required.
minValue	Minimum value of the progressbar. Default: 0.
maxValue	Maximum value of the progressbar. Default: 100.
className	Classes to apply to the svg element. Default: ''.
text	Text to display inside progressbar. Default: ''.
strokeWidth	Width of circular line relative to total width of component, a value from 0-100. Default: 8.
background	Whether to display background color. Default: false.
backgroundPadding	Padding between background circle and path/trail relative to total width of component. Only used if background is true. Default: 0.
counterClockwise	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 for more detail.
styles	Object allowing customization of styles of each svg subcomponent (root, trail, path, text, background).

Theming (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.

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:

import { CircularProgressbar, buildStyles } from 'react-circular-progressbar';

const percentage = 66;

<CircularProgressbar
  value={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,

    // Can specify path transition in more detail, or remove it entirely
    // pathTransition: 'none',

    // Colors
    pathColor: `rgba(62, 152, 199, ${percentage / 100})`,
    textColor: '#f88',
    trailColor: '#d6d6d6',
    backgroundColor: '#3e98c7',
  })}
/>;

buildStyles is a shorthand, but you can also build the styles object yourself. It's an object with root, path, trail, text, and background properties, which are each a set of inline styles to apply to the relevant SVG subcomponent. Here's the equivalent set of styles as above, without using buildStyles:

<CircularProgressbar
  value={percentage}
  text={`${percentage}%`}
  styles={{
    // Customize the root svg element
    root: {},
    // Customize the path, i.e. the "completed progress"
    path: {
      // Path color
      stroke: `rgba(62, 152, 199, ${percentage / 100})`,
      // Whether to use rounded or flat corners on the ends - can use 'butt' or 'round'
      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: {
      // Text color
      fill: '#f88',
      // Text size
      fontSize: '16px',
    },
    // Customize background - only used when the `background` prop is true
    background: {
      fill: '#3e98c7',
    },
  }}
/>

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 for a live example on how to customize styles.

Using CSS

You can also customize styles with CSS. There are equivalent CSS hooks for the root, path, trail, text, and background of the progressbar.

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;
}

Adding arbitrary text or content inside the progressbar

If you want to add multiple lines of text or images within the progressbar, you can overlay it on top of a regular <CircularProgressbar /> using absolute positioning. react-circular-progressbar ships with a CircularProgressbarWithChildren component which makes it easy to do that by using JSX children:

import { CircularProgressbarWithChildren } from 'react-circular-progressbar';

<CircularProgressbarWithChildren value={66}>
  {/* Put any JSX content in here that you'd like. It'll be vertically and horizonally centered. */}
  <img style={{ width: 40, marginTop: -5 }} src="https://i.imgur.com/b9NyUGm.png" alt="doge" />
  <div style={{ fontSize: 12, marginTop: -5 }}>
    <strong>66%</strong> mate
  </div>
</CircularProgressbarWithChildren>;

CircularProgressbarWithChildren has all the same props as CircularProgressbar - you can use it the exact same way otherwise.

Animating text

If you want to animate the text as well as the path, you'll need to transition the value prop from one value to another using a third-party animation library like react-move and an easing library like d3-ease.

You can use a render prop wrapper like AnimatedProgressProvider.js inside this Codesandbox to help manage the transitioning value, and use it like this:

import { easeQuadInOut } from 'd3-ease';

<AnimatedProgressProvider
  valueStart={0}
  valueEnd={66}
  duration={1.4}
  easingFunction={easeQuadInOut}
>
  {(value) => {
    const roundedValue = Math.round(value);
    return (
      <CircularProgressbar
        value={value}
        text={`${roundedValue}%`}
        /* This is important to include, because if you're fully managing the
        animation yourself, you'll want to disable the CSS animation. */
        styles={buildStyles({ pathTransition: 'none' })}
      />
    );
  }}
</AnimatedProgressProvider>;

Animating progressbar upon component mount or upon visible

Upon component mount

In order to trigger the default CSS animation on mount, you'll need to change props.value from 0 to your desired value with a setTimeout in componentDidMount. You can use a wrapper component to help manage this like ProgressProvider.js in this Codesandbox. Then you can do:

<ProgressProvider valueStart={0} valueEnd={66}>
  {(value) => <CircularProgressbar value={value} />}
</ProgressProvider>

Upon visible

To animate the progressbar only when it becomes visible (e.g. if it's below the fold), you can use something like react-visibility-sensor which detects whether the component is visible or not. Here's a Codesandbox example.

Fixing text centering in Internet Explorer (IE)

Because the dominant-baseline CSS property does not work in IE, the text may not be centered in IE.

The recommended way to fix this is to instead of using props.text, use CircularProgressbarWithChildren and put your text in props.children, as described here.

However, you can also work around this by setting the text prop to be a <tspan> element and then adjusting the dy vertical offset, like so:

// Use feature or browser detection to determine if IE
const needDominantBaselineFix = ...

<CircularProgressbar
  value={percentage}
  text={<tspan dy={needDominantBaselineFix ? -10 : 0}>{percentage}</tspan>}
/>

See this Codesandbox example to see this in action.

Advanced usage

• Applying a gradient to the progressbar
• Creating a dashboard/speedometer style progressbar

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 to see how to help contribute to react-circular-progressbar.

License

MIT