Donut
Show part-to-whole values in one or more rings.
Chart ID: donut. Independent import: @revolist/charts/donut.
Live example
Section titled “Live example”Loading chart…
Reading the chart
Section titled “Reading the chart”Compare parts of a whole with a central hole. Multiple value series create concentric rings; compare each ring as its own distribution rather than adding values across rings.
Data requirements
Section titled “Data requirements”Use one category per row and one or more numeric series. Values are finite numbers or explicit nulls; the row mapper does not group or aggregate repeated keys.
The roles below describe the chart's data contract. Generic category/value roles resolve from the dataset; explicitly bind specialized numeric roles as shown in the complete example.
| Data role | Field count |
|---|---|
category | 1 or more |
value | 1 or more |
series | 1 or more |
Download the complete sample data and settings (JSON). See Data & Configuration for mapping, null values, updates and lifecycle rules.
Create this chart
Section titled “Create this chart”Install the package using the installation guide, give the host an explicit height, and call createDonutChart after the host mounts. This factory fixes the chart type to donut.
<div id="chart" style="width: 100%; height: 450px;"></div>Complete runnable TypeScript example with sample data
import { createDonutChart } from '@revolist/charts/donut';
const container = document.getElementById('chart')!;const chart = await createDonutChart({ container, "dataset": { "revision": 0, "source": "client", "categories": [ { "id": "preview-category-0", "label": "North", "path": [ "North" ], "labels": [ "North" ], "depth": 1, "kind": "leaf" }, { "id": "preview-category-1", "label": "South", "path": [ "South" ], "labels": [ "South" ], "depth": 1, "kind": "leaf" }, { "id": "preview-category-2", "label": "West", "path": [ "West" ], "labels": [ "West" ], "depth": 1, "kind": "leaf" }, { "id": "preview-category-3", "label": "East", "path": [ "East" ], "labels": [ "East" ], "depth": 1, "kind": "leaf" } ], "series": [ { "id": "preview-series-0", "label": "Revenue", "columnPath": [ "Revenue" ], "labels": [ "Revenue" ], "kind": "leaf", "prop": "preview-0" } ], "values": [ [ 38 ], [ 27 ], [ 21 ], [ 14 ] ], "analyticalFrame": { "fields": [ { "id": "pivot:category", "label": "pivot:category", "role": "dimension", "semanticType": "category" }, { "id": "pivot:series", "label": "pivot:series", "role": "dimension", "semanticType": "category" }, { "id": "preview-series-0", "label": "Revenue", "role": "measure", "semanticType": "number", "sourceField": "preview-0" } ], "observations": [ { "id": "[\"preview-category-0\",\"preview-series-0\"]", "dimensions": { "pivot:category": { "value": "North", "label": "North", "path": [ "North" ], "labels": [ "North" ] }, "pivot:series": { "value": "Revenue", "label": "Revenue", "path": [ "Revenue" ], "labels": [ "Revenue" ] } }, "measures": { "preview-series-0": 38 } }, { "id": "[\"preview-category-1\",\"preview-series-0\"]", "dimensions": { "pivot:category": { "value": "South", "label": "South", "path": [ "South" ], "labels": [ "South" ] }, "pivot:series": { "value": "Revenue", "label": "Revenue", "path": [ "Revenue" ], "labels": [ "Revenue" ] } }, "measures": { "preview-series-0": 27 } }, { "id": "[\"preview-category-2\",\"preview-series-0\"]", "dimensions": { "pivot:category": { "value": "West", "label": "West", "path": [ "West" ], "labels": [ "West" ] }, "pivot:series": { "value": "Revenue", "label": "Revenue", "path": [ "Revenue" ], "labels": [ "Revenue" ] } }, "measures": { "preview-series-0": 21 } }, { "id": "[\"preview-category-3\",\"preview-series-0\"]", "dimensions": { "pivot:category": { "value": "East", "label": "East", "path": [ "East" ], "labels": [ "East" ] }, "pivot:series": { "value": "Revenue", "label": "Revenue", "path": [ "Revenue" ], "labels": [ "Revenue" ] } }, "measures": { "preview-series-0": 14 } } ], "matrixCells": [ { "categoryId": "preview-category-0", "seriesId": "preview-series-0", "observationId": "[\"preview-category-0\",\"preview-series-0\"]", "measureFieldId": "preview-series-0" }, { "categoryId": "preview-category-1", "seriesId": "preview-series-0", "observationId": "[\"preview-category-1\",\"preview-series-0\"]", "measureFieldId": "preview-series-0" }, { "categoryId": "preview-category-2", "seriesId": "preview-series-0", "observationId": "[\"preview-category-2\",\"preview-series-0\"]", "measureFieldId": "preview-series-0" }, { "categoryId": "preview-category-3", "seriesId": "preview-series-0", "observationId": "[\"preview-category-3\",\"preview-series-0\"]", "measureFieldId": "preview-series-0" } ] } }, "bindings": {}, "presentation": { "dataLabels": false }});
// When the host unmounts:// chart.destroy();Await updates before reading a snapshot or exporting. Call chart.destroy() when the host unmounts. See the live catalog to interact with this type.
Supported options
Section titled “Supported options”Set these fields in chartOptions. The option schema validates supported keys, ranges and choices; updating chartOptions replaces that authored object.
| Option | Default | Accepted values |
|---|---|---|
markOpacity | 1 | 0.2 to 1; step 0.05 |
innerRadius | 0.45 | 0 to 0.95; step 0.05 |
outerRadius | 1 | 0.05 to 1; step 0.05 |
paddingAngle | 0 | 0 to 45; step 0.5 |
cornerRadius | 0 | 0 to 100; step 1 |
arcLabelRadius | 0.7 | 0 to 1; step 0.05 |
arcLabelMinAngle | 0 | 0 to 360; step 1 |
pieHighlight | none | item, series, none |
pieFade | none | series, global, none |
startAngle | -90 | -360 to 360; step 1 |
sweepAngle | 360 | 1 to 360; step 1 |
calloutLabels | false | true or false |
Radius fields are responsive ratios; padding angles and label thresholds use degrees, and corners use SVG pixels. Omitted label radius preserves adaptive ring placement rather than the editor preset. See pie geometry units, defaults and limits.
Titles, legends, theme and labels belong to presentation or the corresponding top-level setting. Axis, color, navigation and interaction support depends on the selected chart; see Data & Configuration.
Related charts
Section titled “Related charts”- Pie — Show the share of a single measure as slices.
- Semi-donut — Show part-to-whole values across a compact semicircle.
- Waffle — Compare part-to-whole values on a compact 100-cell grid.
Charts overview · Installation · Data & Configuration
Slice geometry and labels
Section titled “Slice geometry and labels”Set saved outerRadius, paddingAngle, cornerRadius, arcLabelRadius and
arcLabelMinAngle to size, separate, round and label the slices. Defaults preserve
existing rendering; the label-radius editor preset differs from adaptive omitted
placement. See all units, ranges, defaults, resets and ring behavior.
Highlighting and fading
Section titled “Highlighting and fading”Use saved pieHighlight, pieFade, highlightedArc, fadedArc and highlightedPieItem for source-safe hover/focus geometry and controlled highlighting. See scopes, radius units, callbacks, Pivot controls and export behavior.