Pie highlighting and fading

Standalone Charts and Pivot share saved interaction policies for pie, donut and semiDonut. Highlighting changes presentation while preserving source values, shares, sector order, selection, click/drill records, data views and CSV. There are no transitions or animation in this API.

const dataset = createChartDataset(rows, mapping);
const chart = await createChart({
  container,
  chartType: 'donut',
  dataset,
  chartOptions: {
    outerRadius: 0.85,
    pieHighlight: 'item',
    pieFade: 'global',
    highlightedArc: { additionalRadius: 10, cornerRadius: 8 },
    fadedArc: { additionalRadius: -15, color: '#9ca3af', opacity: 0.25 },
  },
  rendererOptions: {
    pie: { onHighlightChange: item => console.log(item) },
  },
});

Saved scopes and styles

chartOptions field	Default	Behavior
pieHighlight	'none'	'item' highlights the inspected sector; 'series' highlights its whole angular series/ring; 'none' disables highlight and fade paint.
pieFade	'none'	'series' fades other unhighlighted sectors in the inspected ring; 'global' fades every unhighlighted ring/sector; 'none' retains other sectors. Requires a non-none highlight scope.
highlightedArc	{}	Style overrides for highlighted sectors. Omission retains their original geometry and color.
fadedArc	{}	Style overrides for faded sectors. Omitted opacity uses 0.2; geometry/color remain unchanged unless authored.
highlightedPieItem	Omitted	Controlled semantic item { categoryId, seriesId }, or explicit null to force no highlight. Omit the field for pointer/focus-controlled paint.

ChartPieArcStyle supports these optional fields in both style objects:

Field	Units and resolution
innerRadius	Nonnegative SVG pixels, or a decimal percentage string such as '25%'. Overrides the source inner radius for that state.
outerRadius	Same units; overrides the source outer radius before applying additionalRadius.
additionalRadius	Signed SVG pixels added to the resolved outer radius. Negative values shrink it. Default 0.
cornerRadius	Nonnegative SVG pixels; bounds follow the actual arc angle and thickness. Defaults to the ordinary pie cornerRadius.
color	A validated chart color for the arc fill. Source palette/legend and tooltip identity remain unchanged.
opacity	0–1, multiplying existing source mark opacity through the sector group. Highlighted omission preserves opacity; faded omission uses 0.2.

ChartPieRadius is a number or percentage string. Percentages reference the available fitted radius before the ordinary outerRadius ratio is applied. This is different from the ordinary pie innerRadius/outerRadius ratio options. Style lengths and their numeric percentage components are bounded to 1,000,000; additionalRadius accepts the corresponding signed interval. Percentages use decimal syntax with %, without whitespace or units such as px. Invalid values, unknown style/item keys and unsupported chart-type options reject before replacing the current frame.

Resolved outer radii have a zero floor; inner radii are bounded to the resolved outer radius. Large authored arcs can exceed the fitted plot and be clipped by the SVG/export boundary: highlight does not reflow the chart. Reserve space with ordinary outerRadius when expanding arcs. Rounding, spacing, source radius bindings and concentric rings retain their normal contracts.

On-arc labels follow radius changes using their existing arcLabelRadius ratio, or adaptive placement when omitted. Callout anchors follow the changed outer radius. A color-, opacity- or corner-only change retains label placement. Label content, typography, existing density rules and arcLabelMinAngle are unchanged.

Pointer, keyboard and controlled state

Pointer inspection takes precedence over focused inspection. Leaving the chart restores an eligible focused item, otherwise clears transient highlighting. Keyboard focus uses the existing canonical sector targets and activation rules. Escape dismisses transient paint; it does not clear authored controlled state. Saved series/category IDs survive source reordering. Unknown, omitted, hidden or non-plotted controlled identities remain dormant and do not fade unrelated sectors. Use the actual dataset category ID, which may encode the category path; do not substitute its displayed label or source-array index.

await chart.update({ chartOptions: {
  ...chart.model.chartOptions,
  highlightedPieItem: { categoryId: dataset.categories[0].id, seriesId: dataset.series[0].id },
} });

rendererOptions.pie.onHighlightChange receives an owned, frozen ChartPieItemIdentifier or null when requested pointer/focus identity changes. Repeated events over the same item are deduplicated. Controlled paint can stay on another item while notifications report the requested item. Mounting or changing controlled state alone does not notify. The callback is runtime-owned, is not serialized, and does not replace ordinary node-click callbacks. Scope 'none' disables paint while retaining inspection and these notifications.

Models persist all five saved fields. SVG server rendering, in-place hydration and restored charts apply controlled state; transient pointer/focus state is runtime-only. Clean SVG/PNG/PDF snapshots remove transient highlight geometry/paint and retain authored controlled highlighting, without changing the live focused chart. Runtime element styles are restored correctly in those snapshots. Previews remain noninteractive and do not apply these highlight states.

Pivot authoring

Customize → Appearance exposes Pie highlight and Pie fading through the shared option schema, including field reset and appearance reset. The style objects and controlled identity are model/API configuration rather than a new style-object editor. They survive compatible pie/donut/semi-donut changes and are pruned when switching to chart types that do not support them.

For Pivot runtime callbacks, use createPivotChartsRenderer({ pie: { onHighlightChange } }) as the renderer. Public aliases are PivotChartPieItemIdentifier, PivotChartPieArcStyle, PivotChartPieRadius and PivotChartPieRendererOptions. Localize the two control captions/descriptions through localeText.chartOptions.labels.pieHighlight, .pieFade and the matching descriptions entries. Use normal appearance policy IDs chartOptions.pieHighlight and chartOptions.pieFade.

These controls do not add pie center offsets, per-ring composition/geometry objects, sorting, animated radii or transitions. See pie geometry for ordinary radius, spacing, rounding and labels. The upstream MUI pie highlight reference describes the related interaction capability; the bindings and persisted contracts above belong to the framework-neutral Charts engine.