DonutChart

When to use#

Use a DonutChart to show how one whole splits into a few parts, six at most: minutes by repository, runs by result. The ring gives the proportions at a glance and the legend beside it gives each part's value and share, which is where the eye reads them.

Similar#

• BarChart compares the same values by length, one bar each: the better choice when they are many or close.
• AreaChart with isStacked shows how a whole splits over time, not at one moment.
• Progress shows one part of one whole, such as a task 70% done.

A ring with its total#

index names each part and value holds its amount. The middle shows the total over labels.total; a hovered, tapped or focused part takes its place. The numbers on this page are sample data.

import { DonutChart } from "cennge-ui/charts";

const labels = [
  { label: "bug", issues: 3 },
  { label: "enhancement", issues: 8 },
  { label: "documentation", issues: 4 },
  { label: "question", issues: 2 },
];

export default function OpenIssuesByLabel() {
  return (
    <DonutChart
      aria-label="Open issues in cennge-ui by label"
      data={labels}
      index="label"
      value="issues"
      indexLabel="Label"
      valueLabel="Open issues"
      labels={{ total: "Open issues" }}
    />
  );
}

A pie#

variant="pie" fills the middle, so there is no total in it: the picked part's legend row lights up and the other parts fade. Here theme colours carry a meaning: passed in success, failed in danger, cancelled in the grey of default.

import { DonutChart } from "cennge-ui/charts";

const results = [
  { result: "Passed", runs: 1184 },
  { result: "Failed", runs: 63 },
  { result: "Cancelled", runs: 41 },
];

export default function RunsByResult() {
  return (
    <DonutChart
      aria-label="CI runs in October by result"
      data={results}
      index="result"
      value="runs"
      indexLabel="Result"
      valueLabel="Runs"
      variant="pie"
      colors={["success", "danger", "default"]}
    />
  );
}

The small parts as Other#

colors gives the parts their colours in order; without it they take the palette's slots. default is the grey for a part with no colour of its own, such as the rest folded into Other. valueFormat writes the amounts in the middle, the legend and the table; the shares stay percentages in the provider's locale.

import { DonutChart } from "cennge-ui/charts";

const disk = [
  { kind: "Pages", megabytes: 412 },
  { kind: "Media", megabytes: 139 },
  { kind: "Search index", megabytes: 61 },
  { kind: "Logs", megabytes: 33 },
  { kind: "Other", megabytes: 19 },
];

export default function DiskUse() {
  return (
    <DonutChart
      aria-label="Disk used by payload-cache"
      data={disk}
      index="kind"
      value="megabytes"
      indexLabel="Kind"
      valueLabel="Size"
      colors={["chart-1", "chart-2", "chart-3", "chart-4", "default"]}
      valueFormat={(megabytes) => `${megabytes} MB`}
      labels={{ total: "Used" }}
    />
  );
}

Nothing to divide#

A part of zero or less is left out of the ring, and the arrow keys skip it, though the legend still lists it. When no part is left, emptyContent sits in an empty grey ring, or labels.empty ("No data") without it, the legend is gone and nothing takes focus. The table screen readers get still lists every part, at zero.

import { DonutChart } from "cennge-ui/charts";

const failed = [
  { repository: "cennge-ui", runs: 0 },
  { repository: "payload-cache", runs: 0 },
  { repository: "ai-niche-scout", runs: 0 },
];

export default function FailedRuns() {
  return (
    <DonutChart
      aria-label="Failed CI runs this week by repository"
      data={failed}
      index="repository"
      value="runs"
      indexLabel="Repository"
      valueLabel="Failed runs"
      emptyContent="No failed runs this week"
    />
  );
}

Accessibility#

• The figure and the ring are named by aria-label; the ring is a focusable group described by labels.keyboardHint.
• Focus from the keyboard picks the first part at once, and a polite live region reads each part the arrows reach, as "enhancement: 8 (47.1%)".
• The picked part's legend row lights up; the rows of the others keep their full contrast.
• Screen readers get a table of every part with its value and share, and a last row with the total.

Server rendering#

Nothing in a DonutChart waits for a measure: the ring, the total, the legend and the table are all rendered on the server. The ring pops in as it appears; with reduced motion it is there at once.

Props#