Pie Chart¶
Displays a part-to-whole breakdown as circular slices, each sized in proportion to the total. Set an inner radius greater than zero to render a donut chart.
Chart components · element type pie-chart · binds through a data source
Related: Generic Chart · ECharts · Legend Entry
Pie charts work best with a small number of named categories: market share, budget allocation, survey responses, status distribution, and similar summaries. For trends, comparisons across an axis, or multiple independent series, use Generic Chart. Use ECharts only when the required visualization is not covered by the built-in chart elements.
Examples¶
Alt text for the chart
Share of revenue by region in {$params.year}Set as Alt text, so the chart is described in the exported PDF.
Slice label with the formatted value
{$record.region}: {$record.total:n;2}Set as Value Template in data-source mode, so each slice gets an outside label with a leader line.
Options¶
Data¶
The component supports two alternative data modes:
| Mode | Configuration | Behavior |
|---|---|---|
| Keys/Values | A list of keys and values entered in the editor | Each item becomes a slice, for example key North with value 42. |
| Data Source | Data Source, Name Field, Value Field | Reads rows from a report data source and maps the category and numeric value fields explicitly. |
In data-source mode, the data source expression must return an array. The chart does not infer the name and value fields. If either mapping is missing, the chart displays a configuration message; if the source has no rows, it displays No data.. Non-numeric, zero, and negative values do not produce visible slices.
An optional transformation on the data source can filter, sort, limit, group, partition, or compute fields before the chart renders. For high-cardinality data, group the source first and consider a top-N plus Other result instead of rendering every category.
Chart configuration¶
| Option | Description |
|---|---|
| Chart Offset | Four offsets in top right bottom left order. Use them to reserve space for labels and the legend. |
| Pie Chart Size | Total sweep angle in degrees. 360 creates a complete pie or donut. |
| Start Angle | Rotates the first slice. |
| Slice Offset | Separates all slices from the center. |
| Gap between slices in pixels | Adds a pixel gap between neighboring slices. |
| Inner Pie Radius | Controls the donut hole. 0 is a pie; a larger value is a donut. |
| Outer Pie Radius | Controls the outer radius of the slices. |
| Border Radius | Rounds slice corners. This is a slice setting, not part of the general pie geometry. |
| Clockwise | Controls the direction in which slices are laid out. |
A new pie chart is inserted 200px tall. Keep a usable height on the element, especially when adding outside labels.
Accessibility¶
Alt text, in the Accessibility section, is the description a screen reader reads out and the one that travels into the exported PDF's tag tree. It supports text templates, so it can name the measure and the breakdown — Share of revenue by region in {$params.year}.
Left empty, the chart is still described — as simply "Chart" — so an export never contains an undescribed graphic. That keeps the document valid; it does not make it useful, so write a real description for any chart that carries meaning.
Decorative marks the chart as ornament, so it is skipped rather than described. It is rarely the right choice for a chart, and it disables Alt text.
Legend swatches need no description of their own. The coloured shape repeats what the legend text beside it already says, so it is marked as decoration and skipped.
Labels and legend¶
| Option | Description |
|---|---|
| Value Template | Adds an outside label with a leader line to each slice, using text templates. |
| Max Label Width | Maximum width for label text. |
| Lead Length | Length of label leader lines. |
| Inner and Outer Point Radius | Control label positioning relative to slices. |
| Legend Entry Template | Template for each legend label, so legend text can differ from the slice name. |
Value Template is evaluated for the current slice record, so inline data can use {$record.key} and {$record.value}, while data-source mode can use the selected row's fields, such as {$record.region} and {$record.total:n;2}.
Legend Entry Template customizes legend text. The editor provides {$record.name} ({$record.value:n;2}) as an example. The normal legend entry uses the slice name.
The legend can be hidden, positioned left/center/right and top/middle/bottom, arranged horizontally or vertically, and configured to show formatted values. The legend is display-only: clicking an entry does not hide or select a slice.
Colors and themes¶
Colors come from the report theme's chart palette and are assigned by the slice name, so stable category names keep color assignments consistent. Colour handling lives in the Styling section:
| Option | Default | Description |
|---|---|---|
| Use Specific Color Map | Off | Draws from a named colour map instead of the theme's default sequence |
| Color Map Name | Empty | Which map to use, when the above is on. Match this across charts so the same category keeps its colour |
| Use Distant Colors | Off | Spreads colours further apart in the palette, for stronger contrast between neighboring slices |
| Legend Items | From theme | Styling for the chart's own legend entries |
See themes for report-level and element-level chart palette overrides. Avoid hard-coded colors when a theme or named color map can express the requirement.
Notes¶
- Use a pie chart only when comparing parts of one whole is the primary message.
- Keep the number of slices low and group small categories when necessary.
- Make the value field numeric and positive.
- Set Name Field and Value Field explicitly in data-source mode.
- Use a donut hole only when it improves readability; it does not represent a second metric.
- Reserve enough height and offset for outside labels and the legend.