React Grid: Chart API

In addition to users creating their own charts from the grid, charts can also be generated by using the Chart API.

Range Charts

Charts can be created programmatically from a range via the grid's createRangeChart() API. The interface is as follows:

function createRangeChart(params: CreateRangeChartParams): ChartRef | undefined;

function (params: IParams): any;

interface IParams {
  values: any[];
  column: Column;
  colDef: ColDef;
  rowNode: RowNode;
  data: any;
  api: GridApi;
  columnApi: ColumnApi;
  context: any;
}

params: {
  ...
  cellRange: {
    rowStartIndex: number;
    rowStartPinned: string;
    rowEndIndex: number;
    rowEndPinned: string;
    columnStart: string | Column;
    columnEnd: string | Column;
    columns: (string | Column)[];
  }
}

The API returns a ChartRef object when a chartContainer is provided. This is the same structure that is provided to the createChartContainer() callback. The ChartRef provides the application with the destroyChart() method that is required when the application wants to dispose the chart.

Example: Charts in Grid Popup Window

This example shows how charts can be created in the grid's provided popup window. The following can be noted:

• Clicking 'Top 5 Medal Winners' will chart the first five rows of Gold and Silver medals by Country.
• Clicking 'Bronze Medals by Country' will chart Bronze by Country using all rows (the provided cell range does not specify rows).
• Note the 'Bronze Medals by Country' chart is unlinked from the grid as chartUnlinked=true. Notice that sorting in the grid does not affect the chart and there is no chart range in the grid.

// Loading...

Example: Charts in Dashboard

This example passes a chartContainer to the API to place the chart in a location other than the grid's popup window. The following can be noted:

• The charts are placed in div elements outside of the grid.
• The two pie charts are showing aggregations rather than charting individual rows.
• Clicking on a chart highlights the range in the grid for which the chart is based.
• The bar chart is sensitive to changes in the rows. For example if you sort, the chart updates to always chart the first five rows.
• All data is editable in the grid. Changes to the grid data is reflected in the charts.
• The two pie charts have legends beneath. This is configured in the chartThemeOverrides.

// Loading...

Pivot Charts

You can also use the API to create a pivot chart. There are fewer parameters available as the pivot chart is always generated from all data in the grid:

function createPivotChart(params: CreatePivotChartParams): ChartRef | undefined;

interface CreatePivotChartParams {
    chartType: ChartType;
    chartThemeName?: string;
    chartContainer?: HTMLElement;
    chartThemeOverrides?: AgChartTheme;
    unlinkChart?: boolean;
}

The pivot chart params share the same behaviour as the Range Chart Params above.

Example: Pivot Chart

This is an example showing the pivot chart API in action, using a specified chart container.

// Loading...

Saving and Restoring Charts

A chart model that represent all the state information about the rendered charts can be obtained using getChartModels(). These models are returned in a format that can be easily used with the other API methods to later restore the chart.

function getChartModels(): ChartModel[];

interface ChartModel {
    modelType: ChartModelType; // 'range' | 'pivot';
    chartId: string;
    chartType: ChartType;
    cellRange: CellRangeParams;
    chartThemeName?: string;
    chartOptions: ChartOptions<any>;
    suppressChartRanges?: boolean;
    aggFunc?: string | IAggFunc;
    unlinkChart?: boolean;
    chart: any;
    getChartImageDataURL: (params: GetChartImageDataUrlParams) => string;
}

interface GetChartImageDataUrlParams {
    type?: string;
}

Note from the snippet above it is also possible to retrieve a base64 encoded image rendered from the chart in the model using getChartImageDataURL.

These models can then be supplied to the following grid api method to restore the charts:

function restoreChart(model: ChartModel, chartContainer?: HTMLElement): ChartRef

Note that an optional chartContainer can be specified when restoring a chart.

Example: Saving and Restoring Charts

The example below demonstrates how you can save and then later restore a chart. You can make changes to the chart type, theme, data and formatting options and note how the restored chart looks the same as the chart that was saved.

It also shows how you can retrieve images rendered from the chart in multiple formats.

• Create a range chart from the grid, which will be shown in a container below the grid.
• Change the chart type, theme, data and/or formatting in order to see the changes restored later.
• Click "Save chart" to persist a model of the visible chart into a local variable. An alert will be shown to confirm that this has happened.
• Click "Clear chart" to destroy the existing chart.
• Click "Restore chart" to restore the previously saved chart.
• Click "Open PNG" to open a PNG format image of the chart in a new window.
• Click "Open JPG" to open a JPG format image of the chart in a new window.

// Loading...

Next Up

Continue to the next section to learn about: Chart Customisation.