Skip to main content

DonutChart

DonutChart

Pie chart variant with center labels for key metrics

Tags: chart proportion percentage dashboard metric

View Demo

The DonutChart is a variant of the pie chart with a hollow center that can display summary metrics. This design is often preferred for dashboards as it provides a cleaner look and the center space can highlight total values or key metrics.

Reporting props marked Svelte only (valueFormat, showDataTable, exportable, reference lines, data zoom and so on) are available in @classic-homes/charts-svelte; React support is pending.

Import​

<script>
  import { DonutChart } from '@classic-homes/charts-svelte';
</script>
// React
import { DonutChart } from '@classic-homes/charts-react';

Basic Usage​

<script>
  import { DonutChart } from '@classic-homes/charts-svelte';

  const data = [
    { name: 'Completed', value: 65 },
    { name: 'In Progress', value: 25 },
    { name: 'Pending', value: 10 },
  ];
</script>

<DonutChart title="Task Status" {data} centerLabel="Total" centerValue="100" height={400} />

Props​

Chart-Specific Props​

Prop Type Default Description
data PieSliceData[] required Array of slice data
showLabels boolean true Show labels on slices
labelPosition 'inside' | 'outside' 'outside' Position of labels
innerRadius number | string '50%' Inner radius for donut hole
centerLabel string - Text label in the center
centerValue string | number - Value displayed in the center
labelFormatter string | ((params: LabelFormatterParams) => string) - Data label template or function
legend ChartLegendConfig - Built-in legend position, alignment, icon and formatter
onLegendChange (visible: Record<string, boolean>) => void - Called when legend items are shown or hidden
renderLegend Snippet<[LegendRenderProps]> - Custom HTML legend (e.g. ChartLegend) instead of the built-in one; React takes a function returning a node
onClick (params: SliceEventParams) => void - Callback when clicked

Inherited Base Props​

Prop Type Default Description
title string required Chart title for accessibility
height number | string 400 Chart height
theme 'light' | 'dark' | 'auto' 'auto' Theme preference
showLegend boolean true Show chart legend
showTooltip boolean true Show tooltip on hover
tooltipFormatter string | ((items: TooltipFormatterParams[]) => string) - Custom tooltip template or HTML function
tooltipValueFormatter (value: number) => string - Format values in the default tooltip
option EChartsOption - Raw ECharts option deep-merged over the generated one
description string - Optional description for screen readers
minHeight number - Minimum height in pixels; also bounds an 'auto' height
maxHeight number - Maximum height in pixels; also bounds an 'auto' height
loading boolean false Show loading skeleton; over existing data a loading overlay is shown instead (Svelte)
error string | null - Error message to display
onRetry () => void - Show a Retry button on the error state, calling this (Svelte only)
emptyMessage string - Message shown when data is empty
valueFormat ValueFormatPreset | Intl.NumberFormatOptions | ((value: number) => string) - How values are written in value axes, tooltips, labels and the data table: 'number', 'integer', 'compact', 'currency', 'currencyCents', 'percent', 'percentValue', 'days', Intl options or a function (Svelte only)
locale string 'en-US' Locale for valueFormat (Svelte only)
onReady (chart: EChartsType) => void - Called with the ECharts instance when it is created (Svelte only)
events Record<string, (params) => void> - Raw ECharts event handlers keyed by event name, e.g. datazoom (Svelte only)
showDataTable boolean | 'sr-only' 'sr-only' Render the data as a table: 'sr-only' for screen readers, true adds a visible "Show data" toggle, false for none (Svelte only)
exportable boolean | ChartExportConfig false Show PNG and CSV download buttons; or { image, csv, filename } (Svelte only)
patterns boolean false Fill series with decal patterns as well as colour, for colour-blind readers (Svelte only)
class string - Custom CSS class
animation boolean true Enable/disable animations (respects prefers-reduced-motion)
showGrid boolean - Show grid lines (where applicable)

Data Structure​

interface PieSliceData {
  name: string; // Slice label
  value: number; // Slice value
  color?: string; // Optional custom color
}

Examples​

Dashboard KPI​

<DonutChart title="Budget Usage" {data} centerLabel="Spent" centerValue="$45,000" height={300} />

With Labels​

<DonutChart title="Category Distribution" {data} showLabels centerLabel="Items" centerValue="156" />

Custom Inner Radius​

<DonutChart title="Thin Donut" {data} innerRadius="70%" />

Accessibility​

  • Center label and value provide context at a glance
  • Full keyboard navigation support
  • Animations respect reduced motion preferences
On this page