Framework:Javascript Data GridAngular Data GridReact Data GridVue Data Grid

JavaScript Data 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(params) API.

createRangeChart
Function
Used to programmatically create charts from a range.
createRangeChart = (
    params: CreateRangeChartParams
) => ChartRef | undefined;

interface CreateRangeChartParams {
  // The range of cells to be charted. 
  cellRange: CellRangeParams;
  // Suppress highlighting the selected range in the grid. 
  suppressChartRanges?: boolean;
  // The aggregation function that should be applied to all series data. 
  aggFunc?: string | IAggFunc;
  // The type of chart to create. 
  chartType: ChartType;
  // The default theme to use, either a default option or your own custom theme. 
  chartThemeName?: string;
  // Provide to display the chart outside of the grid in your own container. 
  chartContainer?: HTMLElement;
  // Allows specific chart options in the current theme to be overridden. 
  chartThemeOverrides?: AgChartThemeOverrides;
  // When enabled the chart will be unlinked from the grid after creation, any updates to the data will not be reflected in the chart. 
  unlinkChart?: boolean;
}

interface ChartRef {
  // The id of the created chart. 
  chartId: string;
  // The chart instance that is produced by AG Charts which can be used to interact with the chart directly. 
  chart: any;
  // The chart DOM element, which the application is responsible for placing into the DOM. 
  chartElement: HTMLElement;
  // The application is responsible for calling this when the chart is no longer needed. 
  destroyChart: () => void;
}

Properties available on the CreateRangeChartParams interface.

cellRange *
CellRangeParams
Defines the range of cells to be charted. A range is normally defined with start and end rows and a list of columns. If the start and end rows are omitted, the range covers all rows (i.e. entire columns are selected). The columns can either be defined using a start and end column (the range will cover the start and end columns and all columns in between), or columns can be supplied specifically in cases where the required columns are not adjacent to each other. See Add Cell Range for more information.
cellRange: CellRangeParams;

interface CellRangeParams {
  // Start row index 
  rowStartIndex: number | null;
  // Pinned state of start row. Either 'top', 'bottom' or null 
  rowStartPinned?: string | null;
  // End row index 
  rowEndIndex: number | null;
  // Pinned state of end row. Either 'top', 'bottom' or null 
  rowEndPinned?: string | null;
  // Starting column for range 
  columnStart?: string | Column;
  // End column for range 
  columnEnd?: string | Column;
  // Specify Columns to include instead of using `columnStart` and `columnEnd` 
  columns?: (string | Column)[];
}
chartType *
The type of chart to create.
chartType: ChartType;

enum ChartType {
  Column = 'column'
  GroupedColumn = 'groupedColumn'
  StackedColumn = 'stackedColumn'
  NormalizedColumn = 'normalizedColumn'
  Bar = 'bar'
  GroupedBar = 'groupedBar'
  StackedBar = 'stackedBar'
  NormalizedBar = 'normalizedBar'
  Line = 'line'
  Scatter = 'scatter'
  Bubble = 'bubble'
  Pie = 'pie'
  Doughnut = 'doughnut'
  Area = 'area'
  StackedArea = 'stackedArea'
  NormalizedArea = 'normalizedArea'
  Histogram = 'histogram'
}
suppressChartRanges
boolean
By default, when a chart is displayed using the grid, the grid will highlight the range the chart is charting when the chart gets focus. To suppress this behaviour, set suppressChartRanges=true.
Default: false
aggFunc
The aggregation function that should be applied to all series data. The built-in aggregation functions are 'sum', 'min', 'max', 'count', 'avg', 'first', 'last'. Alternatively, custom aggregation functions can be provided if they conform to the IAggFunc interface shown here.
aggFunc: string | IAggFunc;

interface IAggFunc {
    (params: IAggFuncParams) : any
}

interface IAggFuncParams {
  // Values to aggregate 
  values: any[];
  // Column the aggregation function is working on 
  column: Column;
  // ColDef of the aggregation column 
  colDef: ColDef;
  // The parent RowNode, where the aggregation result will be shown 
  rowNode: RowNode;
  // data (if any) of the parent RowNode 
  data: any;
  api: GridApi;
  columnApi: ColumnApi;
  // The context as provided on `gridOptions.context` 
  context: any;
}
chartThemeName
string
The default theme to use for the created chart. In addition to the default options you listed, you can also provide your own custom chart themes.
Options: 'ag-default', 'ag-default-dark', 'ag-material', 'ag-material-dark', 'ag-pastel', 'ag-pastel-dark', 'ag-vivid', 'ag-vivid-dark', 'ag-solar', 'ag-solar-dark'
chartContainer
If the chart is to be displayed outside of the grid then a chart container should be provided. If the chart is to be displayed using the grid's popup window mechanism then leave as undefined.
chartThemeOverrides
Allows specific chart options in the current theme to be overridden. See Overriding Existing Themes.
unlinkChart
boolean
When enabled the chart will be unlinked from the grid after creation, any updates to the data will not be reflected in the chart. See Unlinking Charts.
Default: false

The API returns a ChartRef object when a chartContainer is provided. This is the same structure that is provided to the createChartContainer(chartRef) 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.

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.

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:

createPivotChart
Function
Used to programmatically create pivot charts from a grid.
createPivotChart = (
    params: CreatePivotChartParams
) => ChartRef | undefined;

interface CreatePivotChartParams {
  // The type of chart to create. 
  chartType: ChartType;
  // The default theme to use, either a default option or your own custom theme. 
  chartThemeName?: string;
  // Provide to display the chart outside of the grid in your own container. 
  chartContainer?: HTMLElement;
  // Allows specific chart options in the current theme to be overridden. 
  chartThemeOverrides?: AgChartThemeOverrides;
  // When enabled the chart will be unlinked from the grid after creation, any updates to the data will not be reflected in the chart. 
  unlinkChart?: boolean;
}

interface ChartRef {
  // The id of the created chart. 
  chartId: string;
  // The chart instance that is produced by AG Charts which can be used to interact with the chart directly. 
  chart: any;
  // The chart DOM element, which the application is responsible for placing into the DOM. 
  chartElement: HTMLElement;
  // The application is responsible for calling this when the chart is no longer needed. 
  destroyChart: () => void;
}

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

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

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.

getChartModels
Returns a list of models with information about the charts that are currently rendered from the grid.
getChartModels = () => ChartModel[] | undefined;

interface ChartModel {
  modelType: ChartModelType;
  chartId: string;
  chartType: ChartType;
  cellRange: CellRangeParams;
  chartThemeName?: string;
  chartOptions: ChartOptions<any>;
  suppressChartRanges?: boolean;
  aggFunc?: string | IAggFunc;
  unlinkChart?: boolean;
}

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

restoreChart
Function
Restores a chart using the ChartModel that was previously obtained from getChartModels().
restoreChart = (
    chartModel: ChartModel,
    chartContainer?: HTMLElement
) => ChartRef | undefined;

interface ChartModel {
  modelType: ChartModelType;
  chartId: string;
  chartType: ChartType;
  cellRange: CellRangeParams;
  chartThemeName?: string;
  chartOptions: ChartOptions<any>;
  suppressChartRanges?: boolean;
  aggFunc?: string | IAggFunc;
  unlinkChart?: boolean;
}

interface ChartRef {
  // The id of the created chart. 
  chartId: string;
  // The chart instance that is produced by AG Charts which can be used to interact with the chart directly. 
  chart: any;
  // The chart DOM element, which the application is responsible for placing into the DOM. 
  chartElement: HTMLElement;
  // The application is responsible for calling this when the chart is no longer needed. 
  destroyChart: () => void;
}

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

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.

  • 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.

Downloading Chart Image

It is possible to retrieve a base64 encoded image rendered from the chart using the getChartImageDataURL(params) API. This API returns a string containing the requested data URL which is ideal for saving to a database and downloading the chart image.

getChartImageDataURL
Function
Returns a string containing the requested data URL which contains a representation of the chart image.
getChartImageDataURL = (
    params: GetChartImageDataUrlParams
) => string | undefined;

interface GetChartImageDataUrlParams {
  // The id of the created chart. 
  chartId: string;
  // A string indicating the image format.
  // The default format type is `image/png`.
  // Options: `image/png`, `image/jpeg` 
  fileFormat?: string;
}

The example below demonstrates how you can retrieve images rendered from the chart in multiple formats.

  • Click "Download chart PNG" to download a PNG format image.
  • Click "Download chart JPEG" to download a JPEG format image.
  • Click "Open PNG" to open a PNG format image of the chart in a new window.
  • Click "Open JPEG" to open a JPEG format image of the chart in a new window.

Next Up

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