DonutChart

ImportCopy Anchor Link

import { DonutChart } from '@nizivo/charts/donut-chart';

Static or interactiveCopy Anchor Link

Split. DonutChart has no 'use client'; it renders the ChartInteraction island over the ring when its status is 'ready' and interaction is 'nizivo' (the default since M41), as AreaChart and BarChart do. That island is its keyboard route: one Tab stop over the ring, the arrow keys over the slices, the ChartTooltip card (see Accessibility). interaction="none" renders no island: the ring is static, hovering a segment or its legend row dims the others and swaps the centre in CSS alone, and the frame makes no keyboard claim. In both modes the legend, with every value and share, and the data table carry the same information without a pointer; tableView="details" shows the table to everyone. How to choose.

ExamplesCopy Anchor Link

BasicCopy Anchor Link

import type { JSX } from 'react';
import { DonutChart } from '@nizivo/charts/donut-chart';

interface Channel {
  name: string;
  sales: number;
}

// Figma 03's donut: sales by channel. Five channels fold into three plus "Other" ($7,398).
const CHANNELS: Channel[] = [
  { name: 'Online store', sales: 64120 },
  { name: 'Point of sale', sales: 34526 },
  { name: 'Wholesale', sales: 17263 },
  { name: 'Marketplace', sales: 5210 },
  { name: 'Pop-up', sales: 2188 },
];

const USD: Intl.NumberFormatOptions = {
  style: 'currency',
  currency: 'USD',
  maximumFractionDigits: 0,
};

export function DonutChartExample(): JSX.Element {
  return (
    <DonutChart
      title="Sales by channel"
      summary="Share of total sales, October"
      data={CHANNELS}
      category={(d) => d.name}
      value={(d) => d.sales}
      format={USD}
      labels={{ category: 'Channel', value: 'Sales', total: 'Total sales' }}
    />
  );
}

LocaleCopy Anchor Link

import type { JSX } from 'react';
import { DonutChart } from '@nizivo/charts/donut-chart';

export function DonutChartLocaleExample(): JSX.Element {
  return (
    <DonutChart
      title="Zahlungsarten"
      data={[
        { name: 'Karte', sales: 81250.5 },
        { name: 'Rechnung', sales: 19800 },
      ]}
      category={(d) => d.name}
      value={(d) => d.sales}
      locale="de-DE"
      format={{ style: 'currency', currency: 'EUR', maximumFractionDigits: 0 }}
      center={<span className="nz-donut-chart-value">2 Arten</span>}
      labels={{ category: 'Zahlungsart', value: 'Umsatz', share: 'Anteil', other: 'Andere' }}
    />
  );
}

StatusCopy Anchor Link

import type { JSX } from 'react';
import { DonutChart } from '@nizivo/charts/donut-chart';

interface Channel {
  name: string;
  sales: number;
}

// Figma 03's donut: sales by channel. Five channels fold into three plus "Other" ($7,398).
const CHANNELS: Channel[] = [
  { name: 'Online store', sales: 64120 },
  { name: 'Point of sale', sales: 34526 },
  { name: 'Wholesale', sales: 17263 },
  { name: 'Marketplace', sales: 5210 },
  { name: 'Pop-up', sales: 2188 },
];

export function DonutChartStatusExample(): JSX.Element {
  return (
    <div>
      <DonutChart
        title="Sales by channel"
        status="loading"
        data={[]}
        category={(d: Channel) => d.name}
        value={(d) => d.sales}
      />
      <DonutChart
        title="Sales by channel"
        data={[]}
        category={(d: Channel) => d.name}
        value={(d) => d.sales}
      />
      <DonutChart
        title="Sales by channel"
        status="error"
        data={CHANNELS}
        category={(d) => d.name}
        value={(d) => d.sales}
      />
    </div>
  );
}

FoldingCopy Anchor Link

foldCategories(items, max, otherLabel, sort) is the rule DonutChart applies, exported so a server can compute the same slices:

1. Values that are not finite, or not above zero, are left out.
2. sort="value" (default) orders the rest largest first, ties in input order; sort="none" keeps input order.
3. The first maxCategories (clamped to 1–3) take chart/cat-1, chart/cat-2 and chart/cat-3, in that order.
4. The rest add up into one slice in chart/neutral named labels.other. When exactly one category is left over, that slice keeps its own name.

PropsCopy Anchor Link

Server component. Props: DonutChartProps<T>. Source: src/donut-chart/donut-chart.tsx.

• Also takes every <figure> attribute except children, title.

render takes an element, or, in client code, a function of the props and this state (ChartFrameState):

category and value are an Accessor: a key of the datum whose values have the right type (category="name", which a Server Component can pass), or a (datum, index) => value function, as in every chart. format defaults to Intl.NumberFormat's own options ({}): a fractional value shows its fraction. totalFormat defaults to format in compact notation with at most one fraction digit, and shareFormat to { style: 'percent', maximumFractionDigits: 0 }. All three are plain Intl.NumberFormatOptions, as @nizivo/react's Delta and Meter take them.

labels takes Partial<DonutChartLabels>, which extends ChartFrameLabels (its members are under Other exports). The English defaults, in donutChartLabels, on top of ChartFrame's:

Other exportsCopy Anchor Link

DonutChartLabels type

import type { DonutChartLabels } from '@nizivo/charts/donut-chart'

DonutChart's strings (§16.4), with ChartFrame's. Never concatenated: each is a whole label.

Name	Type	Default	Description
categoryrequired	string	–	The data table's first column header.
hintrequired	string	–	The interactive layer's keyboard instructions.
interactionrequired	string	–	The interactive layer's role, as assistive technology names it.
ofTotalrequired	string	–	After a slice's share in the card and in what the island speaks, for example "52% of total".
otherrequired	string	–	The folded remainder.
pointsrequired	string	–	The interactive layer's name when title is not a string.
sharerequired	string	–	The data table's share column.
totalrequired	string	–	Under the total in the centre.
valuerequired	string	–	The data table's value column.

DonutChartProps type

import type { DonutChartProps } from '@nizivo/charts/donut-chart'

DonutChart's props: its data and formats in the charts' one shape (_core/api.ts) and ChartFrame's, the <figure>'s attributes included. It draws no axes, its legend is its own, the ring is never mirrored, and interaction (default 'nizivo') is the island's keyboard and pointer mode over the slices or, with 'none', a static ring with CSS-only hover and no keyboard claim.

The props of DonutChart, listed above.

DonutChartSort type

import type { DonutChartSort } from '@nizivo/charts/donut-chart'

type DonutChartSort = "value" | "none"

DonutSlice type

import type { DonutSlice } from '@nizivo/charts/donut-chart'

One slice after folding.

Name	Type	Default	Description
labelrequired	string	–
seriesrequired	Exclude<ChartSeries, "current" | "previous">	–
valuerequired	number	–

donutChartLabels constant

import { donutChartLabels } from '@nizivo/charts/donut-chart'

English defaults (§16.4); pass labels to translate per instance.

const donutChartLabels: DonutChartLabels

foldCategories function

import { foldCategories } from '@nizivo/charts/donut-chart'

At most max (1–3) categories plus one "Other" slice (otherLabel), in a stable order: values that are not finite or not above zero are dropped; sort="value" orders the rest largest first, ties in input order; the first max keep chart/cat-1… and the remainder is summed into "Other", which keeps its own label when it is one category.

function foldCategories(items: ReadonlyArray<{ label: string; value: number; }>, max: number, otherLabel: string, sort?: DonutChartSort): DonutSlice[]

Data attributes and slotsCopy Anchor Link

Inside the ChartFrame root, which carries nz-donut-chart (with axes="none", DonutChart's interaction and a vertical Legend in every status, its values and shares only when ready):

CSS hooksCopy Anchor Link

Layers: nz.components. Classes: .nz-chart-frame-body, .nz-chart-frame-caption, .nz-chart-frame-legend, .nz-chart-frame-skeleton, .nz-chart-interaction, .nz-chart-interaction-point, .nz-chart-interaction-tip, .nz-chart-visually-hidden, .nz-donut-chart, .nz-donut-chart-center, .nz-donut-chart-segment, .nz-donut-chart-svg, .nz-donut-chart-value, .nz-legend, .nz-legend-item, .nz-legend-mark.

--nz-donut-chart-size is the ring's size (200 px). Beside the legend the ring is at most 40 % of the chart's width.

Narrow widthsCopy Anchor Link

The chart lays itself out by its own width (ChartFrame is a size container), never the viewport's, so it works the same in a sidebar, a card or on a phone, and on the server, which knows neither:

• Under 24rem, the legend moves under the ring and takes the full width: each row's name wraps in one flexible column, and its value and share never break. The ring takes up to the chart's whole width, centred. There is no room there for the island's card that would neither pass the chart's edge nor cover the ring, so it is not shown: the active slice's share and name fill the centre, its legend row (the others dimmed) shows its value, and the island still speaks it.
• A legend name wraps, a long word too, rather than running into its value, at every width.
• The centre steps down with the ring: Numeric/M over Body/S on a ring under 10rem. On a ring under 6rem the total no longer fits: it is clipped out of sight but stays in the markup, so a screen reader still reads it (it is in no legend row or table cell).

AccessibilityCopy Anchor Link

• The ring is aria-hidden. The legend lists every slice with its value and share, and the data table has one row per slice: both are server HTML.
• The centre's total is readable; the per-slice centres shown on hover are aria-hidden.
• The legend renders in every status so the box does not move, but shows values and shares only when the chart is ready: an error never shows numbers beside "could not be loaded".
• With interaction="nizivo" (default), the island's item mode is the keyboard route (M41). The ring is one Tab stop (role="application", named by title when it is a string, else labels.points; role description labels.interaction; described by labels.hint, visually hidden). Keyboard focus shows the card for the active slice: the first slice, or the last one a key or the pointer showed. ArrowRight and ArrowLeft move to the next and previous slice in data order, which is clockwise; the ring is never mirrored, so dir="rtl" does not flip the keys. Home and End go to the first and last slice. The active segment gets data-highlighted, which dims the other segments to opacity 0.35 and the other legend rows to 0.45 and swaps the centre to its share and name, as hover does.
• The ChartTooltip card sits at the slice's centre, half-way through the band, and opens toward the legend: the slice's name as its title, one row (labels.value, a swatch in the slice's colour, the formatted value) and its share with labels.ofTotal ("52% of total"). Each keyboard move speaks the same through the polite region, joined with the list separators of the chart's locale; with labels={{ value: 'Sales' }}, "Online store, Sales, $64,120, 52%, of total" (donut-chart-interaction.spec.tsx in packages/charts/test/browser). A pointer shows the card for the segment under it and never speaks; over a gap or the hole the card stays as it is.
• Escape hides the card wherever focus is, as in the other island modes. On the focused ring it is consumed and stopped, so an enclosing dialog stays open, a native <dialog> or Dialog; with focus elsewhere it hides a card the pointer opened and still reaches an enclosing dialog (M41).
• With interaction="none", hover is CSS only, with the same dimming, and the frame makes no keyboard claim. The hover state has no Escape; it adds no information the legend does not show. Pass tableView="details" where sighted keyboard users need the data table.
• Forced colours: the four slices take Highlight, Canvas (hollow), CanvasText and GrayText, each outlined in CanvasText (the active slice 3 px), and the legend marks inside the donut match them. Only Chromium's forced-colours emulation has been looked at.
• The ring fades in over --nz-duration-chart-draw, 0 ms under Reduced motion.

KeyboardCopy Anchor Link

With interaction="nizivo" (default):

Source: chart-interaction.client.tsx in packages/charts/src/_island (item mode). donut-chart-interaction.spec.tsx in packages/charts/test/browser checks it. With interaction="none" the ring has no Tab stop and no keys.

FigmaCopy Anchor Link

Donut Chart, 7275:13455: State=Default 7275:13456 and State=Hover 7275:13486, 482 × 200 with the legend. "Share-of-whole chart, max 3 categories + Other. Hover dims non-focused segments to 35%." The ring is 200 px with a 26 px band (outer radius 100, inner 74) and real 3-unit gaps between segments. Notes: docs/figma/03-data-viz.md §4.6.