Data Display

DonutChart

Displays categorical proportions as an accessible donut with an optional center total.

import { DonutChart } from '@lostgradient/cinder';
chart
01

Overview

Reference usage

DonutChart visualizes a small set of part-to-whole values. It exposes visible value labels, an optional center label, series activation, and a horizontal-scroll escape hatch for narrow containers.

Use a bar chart when precise comparison matters more than the part-to-whole relationship.

Usage

svelte 
<script lang="ts">
  import { DonutChart } from '@lostgradient/cinder';

  const data = [
    { id: 'build', label: 'Build', value: 42 },
    { id: 'review', label: 'Review', value: 28 },
    { id: 'test', label: 'Test', value: 18 },
    { id: 'docs', label: 'Docs', value: 12 },
  ];
</script>

<DonutChart label="Workload" {data} centerLabel="Tasks" valueLabels />

label is required because it names both the chart and its non-visual fallback list. valueLabels adds a visible <ul> legend with value labels; centerLabel is supplemental and should not be the only explanation of the total. Use scrollable when the legend or ring cannot fit the container, and provide onSeriesClick only when a series is actionable—otherwise keep the chart informational. When valueLabels is off, a screen-reader-only <ul> remains the non-visual fallback for comparison and screen-reader users (not a data table).

Live preview

Basic donut chart

100Tasks
  • Build 42
  • Review 28
  • Test 18
  • Docs 12

02

When to use

Use when
  • Showing a small number of parts-of-whole categories.
Avoid when
  • Comparing many categories or precise values; use BarChart.
03

Examples

Basic donut chart

A compact breakdown of workload by category.

04

Props

Props for donut-chart
Name
Type
Default
Description
label required text Names both the chart and its non-visual fallback list.
data required DonutChartDatum[] Part-to-whole values rendered as the ring and, when valueLabels is off, as a screen-reader-only fallback <ul> (not a data table). A negative, NaN, or infinite value renders as 0 rather than being rejected—see DonutChartDatum.value.
valueLabels boolean false Adds a visible <ul> legend with value labels below the ring, in place of the screen-reader-only fallback list. Defaults to false.
centerLabel text Supplemental label rendered at the ring's center. Should not be the only explanation of the total.
scrollable boolean false Enables a horizontal-scroll escape hatch for narrow containers. Defaults to false.
onSeriesClick (datum: DonutChartDatum, index: number) => void Called when a series is activated. Provide only when the series is actionable.