@garvae/react-pie-donut-chart

中文文档
1.0.3发布于 2023/03/01MITTypeScriptESM + CJS零依赖近 30 天下载 6019

Lightweight library allows you to create "pie" and "donut" charts easily

原始使用文档
文档目录12 节
  1. Description
  2. Features
  3. 🎬 Demo video
  4. 🔧 Installation
  5. ⚙️Properties
  6. ❕ Required props
  7. ❔ Optional props
  8. 🚀️ Example
  9. 🙋‍♂ Author - Garvae
  10. ❤ Show your support
  11. 🤝 Contributing
  12. 📄 License - MIT

react-pie-donut-chart

Description

This lightweight library allows you to create "pie" and "donut" charts easily

The chart component has very flexible settings. It can accept a passed size or automatically adjust to the size of the parent component. Moreover, this component is accessible.

Features

  • ✔️lightweight
  • ✔️flexible settings
  • ✔️both "Donut" & "Pie" variants
  • ✔️accessible
  • ✔️responsive (svg re-renders when it's needed)
  • ✔️ability to show some text in the center of the chart
  • ✔️ready for TypeScript
  • ✔️detailed documentation
  • ✔️100% Tests-covered

cover


🎬 Demo video


⚠️ If the video is not loading, try going to the GitHub repo or using the direct link

🌐 Demo page coming soon


🔧 Installation

npm install @garvae/react-pie-donut-chart

or

yarn add @garvae/react-pie-donut-chart


⚙️Properties


❕ Required props


Data prop

Chart data. An array of objects (Array<TDataItem>) with properties described below:

NameTypeDefaultRequiredDescription
colorstringundefined-The color of the chart segment. Must be CSS type 'color'. Default generated automatically
ordernumberundefined-Order of segments in a chart. Default generated automatically
segmentIdstringundefined-The unique ID of the chart segment. Default generated automatically
valuenumberundefined+Segment value

parentRef prop - Required if the size prop is not passed

NameTypeDefaultDescription
parentRefRefObjectundefinedRef to the parent HTMLElement

size prop - Required if the parentRef prop is not passed

NameTypeDefaultDescription
sizenumberundefinedChart size


❔ Optional props


NameTypeDefaultDescription
animationSpeednumber200The speed (in milliseconds) of the animation when the values of the chart element change
chartCenterSizenumberundefinedThe name of the chart center class. The "chart center" is the svg element above the main chart. It's kind of like a text background. "Chart center" will not be shown without "chartCenterSize" parameter. Don't use it if you just want to create a donut-type chart, it's better to pass the parameter "donutThickness" instead
children`ReactNodestringnumber`
classNamestringundefinedMain
classNamesstringundefinedChart elements classNames
colorsstringundefinedChart elements colors
resizeReRenderDebounceTimenumber50Prevents unnecessary re-renders. Debounce is disabled when 'resizeReRenderDebounceTime' = 0 or when the value of the "size" property is set
donutThicknessnumberundefinedThe thickness of the donut segments. You should pass this prop if you want to create a donut chart.
fontSizenumberundefinedThe font size. By default, it calculates automatically to fit the size of the whole chart (outer radius) if the chart is "Pie" type. If the chart is "Donut" type this param calculates automatically to fit the size of "donut hole" (inner radius).
gapnumberundefinedGap between segments
hoverScaleRationumber1.05The ratio of the "scale" of the segment when it's hovered, selected or focused
isScaleOnHoverbooleanTRUEEnables or disables "scale" of the segment when it's hovered, active or focused
isSelectOnClickbooleanTRUEEnables or disables segment selection on click on it
isSelectOnKeyEnterDownbooleanTRUEEnables or disables segment selection on "enter" key press on it
isSelectedValueShownInCenterbooleanTRUEEnables or disables the display of the value of the selected segment in the center of the chart
maxSizenumberundefinedChart maximum size.
minSizenumberundefinedChart minimum size
stylesHoveredSegmentCSSPropertiesundefinedYour own styles for hovered, selected or focused segments
onSegmentClick(segmentId: string) => voidundefinedCallback for segment "onClick" event
onSegmentKeyEnterDown(segmentId: string) => voidundefinedCallback for segment "onKeydown" event. Fires only for the "enter" key
selectedstringundefinedSelected segment ID. In most cases you don't need it. But if you want to control this state manually - welcome =)
widthSegmentFocusedOutlinenumber4The width of the "outline" (stroke) of the focused segment. By default, it automatically resizes based on chart size and has a ratio of 0.0066. This means that this stroke width = <chart_size> * 0.0066
tabIndexnumber0Enables or disables chart navigation with a "tab". Default - accessible - you can navigate the chart with the keyboard ("tab" button) And in most cases there is no reason to change it.
textstringundefinedText to show in the center of the chart. By default, it shows the total value of the provided "data" or the value of the selected segment or the value of the focused segment

📌 Notes

You can choose whether you want to resize the chart based on the "parent" size or if you want to set the size manually. If you need a resizable chart, you must be sure that the parent container does not have zero width and height. If you want to set the size manually just add the size property

The Chart has a lot of flexible settings. You can check them out above.

Read more about classNames & colors props below


📌 Additional info about classNames & colors props

classNames prop - Chart elements classNames. An object with following props:
NameTypeDefaultDescription
chartBackgroundstringundefinedChart background className. Background - svg element the same size as the chart, and it is rendered if 'colorSegmentsBackground' property is provided
chartCenterstringundefinedCenter circle (donut hole) className
chartSegmentstringundefinedChart segment className
chartSegmentsBackgroundstringundefinedChart segment background className
childrenstringundefinedChart children className
svgGroupSegmentsstringundefinedChart segments group element className
svgGroupSegmentsBackgroundstringundefinedChart segments group element className. This background is another element under the chart segments group element
svgGroupTextstringundefinedChart text group element className
svgObjectTextstringundefinedChart text element className. is something like element-wrapper for the text container
textstringundefinedText
container className

colors prop - Chart elements colors. An object with following props:
NameTypeDefaultDescription
chartBackgroundstringundefinedColor of the chart background. Background is svg element same size with chart. Not renders if this param was not passed
chartCenterstring#ffffffCenter circle (donut hole) color
segmentFocusedOutlinestring#287bc8Focused segments outline (stroke) color
segmentsBackgroundstringundefinedBackground color of the chart segments background element. Segments background is an svg element same size with chart. 1. Not renders if this param was not passed 2. This is not the segments background. This is background of element under all segments. Sounds complicated, I know... But it needed if you want to create a chart with gaps between segments and to color this space (gap) between segments. When the chart is Pie type this param works same like 'colorChartBackground' prop, but if chart is Donut type then current param will color only the circle under the segments but not the whole chart
textstringundefinedThe color of the text. By default, it will be same color with selected segment (if any segment is selected) or same color with the biggest value in the "data" array.

Make sure the colors provided to the "PieDonutChart" meet the following requirements:

Color must be only HEX string and must be

  • 7-characters starts with "#" symbol - '#ffffff'
  • or 6-characters without "#" symbol - 'ffffff'
  • or 4-characters starts with "#" symbol - '#fff'
  • or 3-characters without "#" symbol - fff


🚀️ Example

import PieDonutChart, { DataItem } from '@garvae/react-pie-donut-chart';
import React from 'react';

const DATA: DataItem[] = [
    {
        color: '#287BC8',
        id: '001',
        order: 1,
        value: 10,
    },
    {
        color: '#D64045',
        id: '002',
        order: 2,
        value: 40,
    },
    {
        color: '#daf6ec',
        id: '003',
        order: 3,
        value: 30,
    },
    {
        color: '#9ED8DB',
        id: '004',
        order: 4,
        value: 20,
    },
    {
        color: '#2B2D42',
        id: '005',
        order: 5,
        value: 50,
    },
];

// "Pie" type chart variant with "parentRef" prop (auto-resize)
const ChartPieAutoResize = () => {
    const ref = React.useRef<HTMLDivElement>(null);

    return (
        <div
            ref={ref}
            style={{ height: '300px', width: '300px' }}
        >
            <PieDonutChart
                data={DATA}
                parentRef={ref}
            />
        </div>
    );
};

// "Pie" type chart variant with "size" prop (no auto-resize)
const ChartPieWithFixedSize = () => {
    return (
        <PieDonutChart
            data={DATA}
            size={300}
        />
    );
};

// "Donut" type chart variant with "size" prop (no auto-resize)
const ChartDonutWithFixedSize = () => {
    return (
        <PieDonutChart
            data={DATA}
            gap={10}
            size={300}
        />
    );
};


🙋‍♂ Author - Garvae

❤ Show your support

Give a ⭐ if this project helped you!

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page. You can also take a look at the contributing guide.



📄 License - MIT

版本与发布记录

@garvae/react-pie-donut-chart 共发布 4 个版本,首次发布于 2022/08/28;过去 12 个月发布了 0 个版本。

版本发布日期距今
1.0.3latest2023/03/013 年前
1.0.22022/08/284 年前
1.0.12022/08/284 年前
1.0.02022/08/284 年前

关于 @garvae/react-pie-donut-chart 的常见问题

@garvae/react-pie-donut-chart 是什么?

Lightweight library allows you to create "pie" and "donut" charts easily

如何安装 @garvae/react-pie-donut-chart?

在项目目录运行 npm install @garvae/react-pie-donut-chart,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=16)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@garvae/react-pie-donut-chart 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@garvae/react-pie-donut-chart 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@garvae/react-pie-donut-chart 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=10。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@garvae/react-pie-donut-chart 可以商用吗?

@garvae/react-pie-donut-chart 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@garvae/react-pie-donut-chart 的下载量有多少?

根据 npm 官方下载统计,@garvae/react-pie-donut-chart 在 2026/10/16 – 2026/11/14 这 30 天内被下载 6,019 次,日均约 201 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@garvae/react-pie-donut-chart 还在维护吗?

最新版本 1.0.3 发布于 2023/03/01(3 年前);至今共发布 4 个版本,其中过去 12 个月发布了 0 个;首次发布于 2022/08/28。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。