Drill Down into a Chart

Drill-down reveals the groups inside a value. For example, open North to compare its product categories, then use a breadcrumb to return to all regions.

Try activating a chart mark, then returning to the first breadcrumb. Drill-down changes the displayed level; it does not mean editing the source orders. Viewing underlying source records is a separate analysis task.

A hierarchy must exist in the report. Learn Pivot drill-down before configuring synchronization between table and chart.

Start from a Pivot cell

Interactive example

Drill and selection

Create a chart using the analytical scope of a selected Pivot coordinate.

With pivotChartsUi.contextMenu: true and ContextMenuPlugin installed, right-clicking a Pivot analytical body cell contributes Pivot Chart…. Creation resolves scope from committed Pivot metadata:

group values open their immediate children;
leaf values open siblings under the same parent;
subtotal and grand-total cells use the nearest valid breakdown;
the clicked column member and measure seed the series selection;
values-on-rows retain the clicked category measure.

The context action composes with other menu contributions. It does not replace application items or depend on visible DOM text.

Click or focus a chart mark

With the default interaction.mode: 'drill', pointer click and keyboard activation first look for an automatic semantic drill target. When the category or series can drill, activation starts the appropriate row, column, or two-axis drill action and does not emit pivot-chart-node-click. The event is emitted only when no automatic drill target exists.

The chart ref supports row, column, and two-axis targets:

1
if (chart.canDrillDown({ axis: 'row', category })) {
2
  await chart.drillDown({ axis: 'row', category });
3
}
4

5
await chart.drillDown({ axis: 'column', series });
6
await chart.drillDown({ axis: 'both', category, series });

Use canDrillDown before offering an application-owned drill control. It checks hierarchy identity, level, child state, and the current active scope.

Each successful frame is stored in PivotChartDrillState.frames. The compact breadcrumb shows the active row and column labels:

1
await chart.drillUp();
2
await chart.drillTo(1);
3
await chart.resetDrill();

Selecting All data resets to the root. Selecting an ancestor calls drillTo directly; it does not replay every intermediate click. After a successful UI drill, focus moves to the current breadcrumb item.

Loading, cancellation, and retry

Drill loads are abortable and revision-checked:

the last successful frame stays visible while the next frame loads;
a newer action aborts or supersedes older work;
stale provider completions are ignored;
rendering failures roll back model and dataset state;
successful scopes are cached;
failed drill metadata is retained for retryDrill().

The dialog displays the pending target, failure message, and retry action without discarding the previous chart.

Keep the table and chart in sync

drillSyncMode controls the relationship between chart navigation and the Pivot frontier:

Mode	Behavior
`chart`	Navigate only in the chart.
`pivot`	Synchronize the Pivot frontier and let the linked Pivot refresh drive the chart.
`both`	Commit the chart frame and synchronize the Pivot.
`event`	Emit `pivot-chart-drill-sync`; the application owns synchronization.

For pivot and both, the active PivotPlugin applies the semantic frontier unless pivotCharts.synchronizeDrill is provided. The custom adapter receives the event detail and an AbortSignal.

1
grid.pivotCharts = {
2
  renderer: createPivotChartsRenderer(),
3
  defaultDrillSyncMode: 'event',
4
  async synchronizeDrill(detail, { signal }) {
5
    await saveAnalyticsRoute(detail.to, { signal });
6
  },
7
};

Common mistakes

A flat report has no child level to open. Add a row hierarchy first.
An empty breakdown can be a valid filtered result. Keep loading failures distinct from “no records”.
When chart and Pivot layouts differ, use chart-only or application-controlled synchronization; a different layout cannot safely follow shared expansion state.

Next steps

Continue with filtering and selection or server-side chart data.