Filtering and Selection

Selection answers “which marks am I interested in?” Filtering answers “which records should remain in the report?” Choose the behavior deliberately: a selected bar can highlight itself, filter the linked Pivot, or ask your application what to do.

Try selecting a region, inspect the table or peer chart, and clear the selection. Use chart-local filters when only this chart should show a different dataset.

Interactive example

Filters and navigation

Select chart members and apply their analytical scope to the linked Pivot.

The live example lets you compare selection and filtering. Watch the source Pivot report as well as the chart, then clear the selection to confirm which view changes.

Select values or filter the report

interaction.mode chooses what mark activation does. It is independent of drillSyncMode:

Mode	Behavior
`drill`	Use the existing automatic hierarchy navigation.
`select`	Commit a persistent semantic selection.
`filter`	Commit selection and apply its member predicates through Pivot.
`event`	Emit a selection proposal for the application without committing or drilling.

These modes are supported by grouped columns/bars, line, column-line, area-line, pie/donut, annotated time series, and small multiples. Other chart families reject unsupported modes. Check the chart definition’s interactionModes before offering custom controls.

1
await chart.update({
2
  interaction: {
3
    mode: 'select',
4
    selectionMode: 'multiple',
5
    crossHighlight: true,
6
  },
7
});

Ordinary activation replaces the selection, or clears an already selected single target. In multiple mode, Ctrl/Meta activation adds or removes a target. Pointer clicks and Enter/Space use the same rules. Selected marks have a visible outline and aria-pressed state. Use the clear action or Escape to clear selection. In Event mode, these user actions request clearing; the application commits the change.

In Display, compose a selection in Select mode, then choose Apply selection as filter. The immediate Filter mode narrows the source chart as well as the linked Pivot. Choose Edit selection to release that chart’s filter while keeping its selection, revise the selected members, and apply again. Other charts’ contributions and user filters remain active.

Semantic identity and persistence

Selection targets store row and column { field, value } members and an optional measure identity. They do not store visible indexes or display labels:

1
await chart.setSelection([
2
  {
3
    row: [{ field: 'region', value: 'North' }],
4
    column: [{ field: 'year', value: 2026 }],
5
    measure: { prop: 'sales', aggregator: 'sum' },
6
  },
7
]);
8
await chart.clearSelection();

Linked projections supply their committed layout fields. Standalone datasets must provide hierarchy level fields or explicit selectionFields: { row: ['region'], column: ['year'] }, aligned with category and series paths. Missing or ambiguous mappings fail rather than interpreting labels as source fields. Measure carriers in values-on-rows layouts never become raw member predicates.

Strings, finite numbers, booleans, and null retain their typed identity. Missing/null source members share the canonical blank value null; negative zero is normalized to zero. Refresh, drill, reordering, and temporarily absent members preserve semantic selection. Rendering only matches current members; it does not replay a filter or emit activation events.

interaction updates replace the authored object: omit it to retain it or use {} to reset. selection: [] clears selection. Save/restore includes both fields. Unlinking releases that chart’s native filter; relinking or restoring a linked Filter chart applies its persisted contribution once.

Native filters and peer highlighting

A chart’s selected tuples combine with OR, and fields inside a tuple combine with AND. Selecting (North, 2026) and (South, 2027) therefore excludes (North, 2027) and (South, 2026). Independent chart owners, ordinary member filters, Core source filters, and result filters combine with AND.

Pivot owns these contributions. Clearing, editing, unlinking, or destroying a chart removes only its contribution. Contributions are ephemeral in Pivot configuration; the chart model owns their persistence. If a layout change removes a predicate field, Pivot drops the entire affected contribution after a successful commit rather than weakening its tuples. Prevented, failed, or superseded selection operations retain the committed chart model. If rendering fails after filtering and restoring the previous native contribution also fails, Pivot retires that owner and reports a selection error. Future queries omit the owner; the last committed remote view remains until a successful refresh.

Destroying a chart disposes its filter owner even when ordinary configuration updates are prevented. If the server cannot refresh during disposal, a selection error reports the cleanup failure and the last committed remote view remains visible. The disposed contribution is removed from future queries; it is not retained as a hidden filter after its chart is gone.

Native filtering requires a linked active Pivot and meaningful source member predicates. Dimensionless totals, synthetic Top/Bottom Other members, and ambiguous field mappings cannot be used as raw filters. A server adapter that explicitly advertises filter: false cannot apply a native chart filter.

Peer highlighting requires crossHighlight: true on both participating charts. It compares shared dimension fields across layouts and leaves unrelated charts unaffected. Measure identity distinguishes local selected cells; peer matching uses dimensions. Highlight updates are silent and are not copied into each peer’s persisted selection.

Application-controlled selection

In Event mode, listen for pivot-chart-selection-request, inspect its semantic proposal, and explicitly call setSelection when the application accepts it:

1
grid.addEventListener('pivot-chart-selection-request', async event => {
2
  const { chartId, proposed } = event.detail;
3
  if (await acceptSelection(proposed)) {
4
    await charts.setChartSelection(chartId, proposed);
5
  }
6
});

pivot-chart-before-selection is preventable. Committed changes emit pivot-chart-selection-changed; failures emit pivot-chart-selection-error. Details include chart ID, operation ID, revision, origin, interaction mode, proposed selection, and current selection. Received highlighting and redraws never emit these selection actions.

Custom user Clear controls should call charts.requestChartSelectionClear(chartId, origin) so Event mode can delegate the request. chart.clearSelection() and charts.clearChartSelection(chartId) are explicit application commits, including in Event mode.

Common mistakes

Use select/highlight behavior for emphasis and filter behavior for source reduction; a selected mark does not always filter the report.
Chart-local query filters and chart-owned shared filters are separate. Clearing one chart’s selection releases only that chart’s filter contribution.
Event mode asks the application to accept a selection; the application must commit it explicitly.

Next steps

See navigation and accessibility, Pivot filtering and the interaction API.