React Circular Progressbar

React Circular Progressbar is a highly customizable circular progress indicator component built with React and SVG. It offers extensive theming capabilities through CSS and inline styles, supports arbitrary content placement within the progressbar, and provides features like custom value ranges, rotation options, stroke width customization, and animation controls.

Package Information

• Package Name: react-circular-progressbar
• Package Type: npm
• Language: TypeScript
• Installation: npm install react-circular-progressbar

Core Imports

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

With children support:

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

For style customization:

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

Basic Usage

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

function App() {
  const percentage = 66;
  
  return (
    <div style={{ width: 200, height: 200 }}>
      <CircularProgressbar value={percentage} text={`${percentage}%`} />
    </div>
  );
}

Architecture

React Circular Progressbar is built around several key components:

• CircularProgressbar: Core component rendering SVG-based circular progress indicator
• CircularProgressbarWithChildren: Wrapper component enabling arbitrary content placement inside the progressbar
• buildStyles: Utility function for generating style objects with common customization options
• SVG Path System: Internal Path component handling circular path rendering with customizable dash patterns
• Style System: Comprehensive styling through CSS classes and inline styles with full customization of all visual elements

Type System Architecture:

The component's type system is designed around inheritance for flexibility:

• CircularProgressbarDefaultProps: Defines all default values that the component provides (all required)
• CircularProgressbarProps: Extends default props and adds the required value property
• CircularProgressbarWrapperProps: Defines optional props for wrapper components (all optional except value)
• CircularProgressbarWithChildrenProps: Extends wrapper props and adds optional children property

This design allows the main component to have comprehensive defaults while wrapper components remain flexible.

Capabilities

Core Progress Display

Primary circular progressbar component with extensive customization options for displaying progress values from 0-100 or custom ranges.

interface CircularProgressbarProps extends CircularProgressbarDefaultProps {
  value: number;
}

interface CircularProgressbarDefaultProps {
  background: boolean;
  backgroundPadding: number;
  circleRatio: number;
  classes: {
    root: string;
    trail: string;
    path: string;
    text: string;
    background: string;
  };
  className: string;
  counterClockwise: boolean;
  maxValue: number;
  minValue: number;
  strokeWidth: number;
  styles: CircularProgressbarStyles;
  text: string;
}

interface CircularProgressbarStyles {
  root?: React.CSSProperties;
  trail?: React.CSSProperties;
  path?: React.CSSProperties;
  text?: React.CSSProperties;
  background?: React.CSSProperties;
}

Core Progressbar

Content Integration

Wrapper component that allows placing arbitrary JSX content inside the progressbar with automatic centering and responsive sizing.

interface CircularProgressbarWithChildrenProps extends CircularProgressbarWrapperProps {
  children?: React.ReactNode;
}

interface CircularProgressbarWrapperProps {
  value: number;
  background?: boolean;
  backgroundPadding?: number;
  circleRatio?: number;
  classes?: {
    root: string;
    trail: string;
    path: string;
    text: string;
    background: string;
  };
  className?: string;
  counterClockwise?: boolean;
  maxValue?: number;
  minValue?: number;
  strokeWidth?: number;
  styles?: CircularProgressbarStyles;
  text?: string;
}

Content Integration

Style Customization

Utility function for generating comprehensive style objects with common customization options like colors, transitions, and rotations.

function buildStyles(options: {
  rotation?: number;
  strokeLinecap?: any;
  textColor?: string;
  textSize?: string | number;
  pathColor?: string;
  pathTransition?: string;
  pathTransitionDuration?: number;
  trailColor?: string;
  backgroundColor?: string;
}): CircularProgressbarStyles;

Style Customization