Donut Chart API
Complete API reference for the Donut Chart. Uses the donut-chart headless engine (extends pie-chart) with donut-specific configuration including data center display.
Data Format
Each dataset entry represents a slice of the donut with a name and numeric value. Same format as PieChartData.
type DonutChartData = {
datasets: { name: string; value: number }[];
};AG Style Config
Donut
| Property | Type | Default | Description |
|---|---|---|---|
| donut.thicknessRatio | number | 0.4 | Thickness of the donut ring as a ratio (0 to 1). Controls the difference between outer and inner radius. |
Pie
| Property | Type | Default | Description |
|---|---|---|---|
| pie.innerRadiusRatio | number | 0.6 | Inner radius ratio (auto-computed from thicknessRatio). |
Data Center
| Property | Type | Default | Description |
|---|---|---|---|
| dataCenter.visible | boolean | false | Whether the center label/value display is visible. |
| dataCenter.mode | "hovered-or-total" | "total" | "hovered" | "hovered-or-total" | Display mode for center content. |
| dataCenter.gap | number | 4 | Gap between label and value text in the center. |
| dataCenter.labelColor | string | "#6b7280" | Color of the center label text. |
| dataCenter.labelFontSize | number | 12 | Font size of the center label. |
| dataCenter.valueColor | string | "#181d1f" | Color of the center value text. |
| dataCenter.valueFontSize | number | 24 | Font size of the center value. |
| dataCenter.valueFontWeight | string | "700" | Font weight of the center value. |
| dataCenter.formatter | (args: { total, hoveredSegment, mode }) => { label: string; value: string } | Shows hovered name/value or "Total" | Formatter function for center display content. |
Radial
| Property | Type | Default | Description |
|---|---|---|---|
| radial.visible | boolean | true | Whether radial labels and ticks are visible. |
| radial.gap | number | 6 | Gap between the donut and radial labels. |
Data Label
| Property | Type | Default | Description |
|---|---|---|---|
| dataLabel.visible | boolean | false | Whether data labels on slices are visible. |
| dataLabel.fontSize | number | 12 | Data label font size. |
| dataLabel.fontColor | string | "white" | Data label text color. |
| dataLabel.radiusRatio | number | 0.65 | Position of data label as ratio of radius. |
Toast Style Config
Donut
| Property | Type | Default | Description |
|---|---|---|---|
| donut.thicknessRatio | number | 0.4 | Thickness of the donut ring as a ratio (0 to 1). |
Pie
| Property | Type | Default | Description |
|---|---|---|---|
| pie.innerRadiusRatio | number | 0.6 | Inner radius ratio (auto-computed from thicknessRatio). |
Data Center
| Property | Type | Default | Description |
|---|---|---|---|
| dataCenter.visible | boolean | false | Whether the center label/value display is visible. |
| dataCenter.mode | "hovered-or-total" | "total" | "hovered" | "hovered-or-total" | Display mode for center content. |
| dataCenter.gap | number | 2 | Gap between label and value text in the center. |
| dataCenter.labelColor | string | "#9ca3af" | Color of the center label text. |
| dataCenter.labelFontSize | number | 11 | Font size of the center label. |
| dataCenter.valueColor | string | "#111827" | Color of the center value text. |
| dataCenter.valueFontSize | number | 22 | Font size of the center value. |
| dataCenter.valueFontWeight | string | "700" | Font weight of the center value. |
| dataCenter.formatter | (args: { total, hoveredSegment, mode }) => { label: string; value: string } | Shows hovered name/value or "Total" | Formatter function for center display content. |
Radial
| Property | Type | Default | Description |
|---|---|---|---|
| radial.visible | boolean | false | Whether radial labels and ticks are visible. |
| radial.gap | number | 8 | Gap between the donut and radial labels. |
Data Label
| Property | Type | Default | Description |
|---|---|---|---|
| dataLabel.visible | boolean | false | Whether data labels on slices are visible. |
| dataLabel.fontSize | number | 14 | Data label font size. |
| dataLabel.fontColor | string | "white" | Data label text color. |
| dataLabel.radiusRatio | number | 0.65 | Position of data label as ratio of radius. |
Custom Parts
Override any visual element by providing a custom builder function: (args, context) => Widget
| Part | Args | Description |
|---|---|---|
| layout | { title: Widget; legends: Widget[]; plot: Widget } | Top-level layout composing title, legends, and the plot area. |
| plot | { dataView: Widget; tooltipArea: Widget; radialItems: DonutChartRadialItem[] } | The plot area with data view, tooltip, and radial items. |
| dataView | { segments: DonutChartSegment[]; dataCenter: Widget } | Container for all donut segments and the center display. |
| segment | { index: number; name: string; value: number; percentage: number; startAngle: number; sweepAngle: number; dataLabel: Widget; isHovered: boolean } | Individual donut segment/slice. |
| dataLabel | { index: number; name: string; value: number; percentage: number; startAngle: number; sweepAngle: number } | Data label on a donut segment. |
| dataCenter | { total: number; hoveredSegment: DonutChartSegmentArgs | null } | Center display showing total or hovered segment info. |
| radialLabel | { index: number; name: string; value: number; percentage: number; angle: number; isHovered: boolean } | Radial label outside the donut. |
| radialTick | { index: number; name: string; value: number; percentage: number; angle: number; isHovered: boolean } | Radial tick line connecting donut to label. |
| legend | { name: string; index: number; isVisible: boolean } | Individual legend item. |
| title | undefined | Chart title element. |
| tooltip | HoveredDonutChartSegment | Tooltip content for a hovered segment. |
| tooltipArea | { tooltip: Widget | null; hoveredSegment: HoveredDonutChartSegment | null } | Tooltip positioning area. |
Context: DonutChartContext
Available in every custom builder via the second argument.
| Name | Type | Kind | Description |
|---|---|---|---|
| data | DonutChartData | property | Current chart data (filtered by hidden series). |
| legends | string[] | property | All legend names from the raw data. |
| width | number | property | Current chart width in pixels. |
| height | number | property | Current chart height in pixels. |
| hiddenSeries | ReadonlySet<string> | property | Set of currently hidden series names. |
| hoveredIndex | number | null | property | Index of the currently hovered segment. |
| config | TConfig | property | The resolved chart configuration object. |
| isSeriesVisible(name) | (name: string) => boolean | method | Check if a series is currently visible. |
| toggleSeries(name) | (name: string) => void | method | Toggle visibility of a series. |
| showAllSeries() | () => void | method | Show all hidden series. |
| hoverSegment(index) | (index: number) => void | method | Set hover state on a segment. |
| unhoverSegment(index?) | (index?: number) => void | method | Clear hover on a segment. |
| unhoverAllSegments() | () => void | method | Clear all segment hover state. |
| isSegmentHovered(index) | (index: number) => boolean | method | Check if a specific segment is hovered. |
| setSize(width, height) | (width: number, height: number) => void | method | Update chart dimensions. |
Custom Part Example
import { ToastDonutChart } from "@/components/flitter/charts/toast-donut-chart";
<ToastDonutChart
data={data}
config={{
donut: { thicknessRatio: 0.3 },
dataCenter: { visible: true },
}}
/>