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.

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:

• Rotating progressbar
• Making the progressbar a gradient
• Putting progressbar around an image
• Customizing the background

Contributing

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

License

MIT