Charts from Grid Data

GridChartsPlugin, imported from @revolist/charts/grid, connects Core RevoGrid to Charts. Declare the chart containers and mappings in grid.gridCharts. The plugin creates the charts, follows grid changes, and cleans up when the grid or plugin is removed. Pro is not required. Normal setup requires no plugin lookup, ready calls, or connection lookup. Ordinary Charts imports do not load the optional Core integration.

Create charts through props

Install Core RevoGrid and Charts. Register RevoGrid as usual, then run the configuration below on the client after the grid and chart containers are mounted.

<revo-grid id="sales-grid" style="height: 280px;"></revo-grid>
<div id="revenue-chart" style="width: 100%; height: 360px;"></div>

import * as charts from '@revolist/charts';
import { GridChartsPlugin } from '@revolist/charts/grid';

const grid = document.querySelector<HTMLRevoGridElement>('#sales-grid')!;
grid.columns = [
  { prop: 'product', name: 'Product', sortable: true },
  { prop: 'revenue', name: 'Revenue' },
  { prop: 'cost', name: 'Cost' },
];
grid.source = [
  { id: 'a', product: 'Alpha', revenue: 100, cost: 60 },
  { id: 'b', product: 'Bravo', revenue: 150, cost: 80 },
];
grid.gridCharts = {
  runtime: charts,
  onError: (error) => console.error(error),
  charts: [
    {
      container: '#revenue-chart',
      chartType: 'groupedColumn',
      scope: 'view',
      mapping: {
        category: { prop: 'product' },
        series: [{ prop: 'revenue' }, { prop: 'cost' }],
      },
    },
  ],
};
grid.plugins = [...(grid.plugins ?? []), GridChartsPlugin];

Sorting changes chart category order, filtering excludes rows, and committed grid edits and source replacements refresh chart values. Scrolling does not change the dataset: offscreen rows remain included.

For a smaller runtime, supply an object with your chart factory and createChartDataset instead of the complete Charts namespace.

Container selectors and elements

container accepts an HTML element or a CSS selector:

container: '#myElement';
// Or pass an element reference:
container: chartElement;

Selectors use the grid’s document and select the first matching element when the chart is created. The target must be an HTML element that already exists and has a usable width and height. Invalid selectors, missing matches, and SVG matches reject chart creation and reach onError. There is no polling for later targets; mount the target and replace grid.gridCharts to retry.

Selectors do not cross shadow roots. Pass an element reference for a container inside a shadow root. A selector is resolved again when a replacement configuration creates its charts; removing a container alone does not dispose its connection.

Column mappings and row identity

Category and series mappings use prop, matching ColumnRegular['prop']. String and numeric column props are supported. Series labels come from column names unless the mapping supplies an explicit label.

getRowId is optional. By default, identity combines the row viewport and physical source index. Sorting and filtering preserve it because it does not use the visible row position. Records are never mutated and need no id property. Replacing a record at the same source index retains that slot’s identity.

Inserting, removing, or rearranging source records can make a captured physical slot refer to a different record. For captured regions that should follow records across those changes or remote reloads, provide a stable application key:

grid.gridCharts = {
  ...grid.gridCharts!,
  getRowId: (row) => String(row.id),
};

An explicit callback must return a unique string or finite number for each included record. The mapped category prop supplies the displayed category text, so duplicate product names are allowed. Each row becomes one chart category; there is no automatic aggregation. Measures must be finite numbers or null, so normalize numeric editor values in the application when necessary.

Choose the data scope

Scope	Rows included
view (default)	All untrimmed rows, in the grid’s current sort order.
source	Loaded source rows in source order, independently of sorting and filtering.
selection	Selected cells within the mapped series.

These scopes describe the loaded grid data. They do not fetch unloaded remote records. Use the provider with regular records; Pivot/group summaries and parent hierarchies require separately authored chart datasets.

Chart selected regions

Enable grid range selection and set the chart’s scope in its props:

grid.range = true;
grid.gridCharts = {
  ...grid.gridCharts!,
  charts: [
    {
      container: '#revenue-chart',
      chartType: 'groupedColumn',
      scope: 'selection',
      selection: { behavior: 'follow', empty: 'empty' },
      mapping: {
        category: { prop: 'product' },
        series: [{ prop: 'revenue' }, { prop: 'cost' }],
      },
    },
  ],
};

For disjoint regions, register MultiRangeSelectionPlugin alongside GridChartsPlugin. Overlapping selected cells are deduplicated. Unselected intersections become null rather than zero or unrelated values. The configured category prop remains available even when it is outside the selected region.

behavior: 'follow' follows current selection coordinates. Use behavior: 'captured' to capture the selected row IDs and column props when the chart is created. Captured regions ignore later selections, follow grid sorting, and omit filtered records until they return. Create or replace the captured chart configuration after selecting the desired region.

empty: 'empty' clears data when nothing is selected. empty: 'view' explicitly falls back to the full view. Selecting only category columns produces an empty chart because no mapped measures are selected.

Multiple charts and pinned rows

Add definitions to the charts array to create multiple charts with independent mappings and scopes. Give each chart its own container.

The main rgRow viewport is included by default. Include pinned rows explicitly:

grid.gridCharts = {
  ...grid.gridCharts!,
  rowTypes: ['rowPinStart', 'rgRow', 'rowPinEnd'],
};

Row IDs must be unique across included viewports. Pinned and reordered columns are resolved through their own grid coordinate spaces.

Updates and automatic cleanup

Assign a new grid.gridCharts object to replace chart definitions. Existing connections close and the new definitions are created automatically. Set the property to undefined to close all charts. Mutating the same configuration object in place does not trigger a rebuild.

Removing the grid, or removing GridChartsPlugin from grid.plugins, destroys all its charts and releases subscriptions. No provider disposal is required. Framework integrations should assign the gridCharts property on their grid element reference and let normal grid teardown handle cleanup.

Optional imperative API

Use this only when an application needs to create charts imperatively or control a particular connection. Omit the charts array and call plugin.connect() on the mounted plugin instance, or add a connection alongside the declared charts. The same container, mapping, scope, and selection options apply.

plugin.ready waits for declared charts and rejects on initialization failure. plugin.connections exposes chart references in creation order. These controls are optional and are not needed for declarative setup. A connection can switch scope with setScope() or capture the current region with captureSelection().

plugin.refresh() refreshes charts after direct record mutations outside observable grid APIs. Initialization failures reach onError and close that configuration’s charts; replace the property to retry. Both declared and imperative charts receive automatic cleanup.