Results:
Loading...
Javascript Data GridJavascriptReact Data GridReactAngular Data GridAngularVue Data GridVue

Vue Data GridRange Chart APIEnterprise

This section shows how Range Charts can be created via the Grid API.

Creating Range Charts

Range Charts can be created through gridApi.createRangeChart() as shown below:

this.gridApi.createRangeChart({
     chartType: 'groupedColumn',
     cellRange: {
         rowStartIndex: 0,
         rowEndIndex: 4,
         columns: ['country', 'gold', 'silver'],
     },
     // other options...
 });

The snippet above creates a Range Chart with the groupedColumn chart type using data from the first 4 and the country, gold, silver columns. For a full list of options see Range Chart API.

The following example demonstrates how Range Charts can be created programmatically via gridApi.createRangeChart(). Note the following:

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

Range Chart Dashboard

The following example passes a Chart Container to the API to place the chart in a location other than the grid's popup window. Note the following:

  • The charts are placed in div elements outside 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.

Hiding Chart Ranges

In some cases it may be desirable to hide the chart ranges in the grid, see Combination Charts.

To hide the chart ranges simply enable suppressChartRanges=true on the ChartRangeParams.

For more details refer to Range Chart API.

Combination Charts

It is possible to create the following combination chart types via gridApi.createRangeChart():

  • Column & Line (chartType: 'columnLineCombo')
  • Area & Column (chartType: 'areaColumnCombo')
  • Custom Combination (chartType: 'customCombo')

When the customCombo chart type is specified a new CreateRangeChartParams.seriesChartTypes must also be supplied. Also note that when seriesChartTypes is present a customCombo chart type is assumed, regardless of which chartType is supplied.

The seriesChartTypes property accepts an array of SeriesChartType objects as shown below:

api.createRangeChart({
     chartType: 'customCombo',
     cellRange: {
       columns: ['month', 'rain', 'pressure', 'temp'],
     }, 
     seriesChartTypes: [
       { colId: 'rain', chartType: 'groupedColumn', secondaryAxis: false },
       { colId: 'pressure', chartType: 'line', secondaryAxis: true },
       { colId: 'temp', chartType: 'line', secondaryAxis: true }
     ], 
     aggFunc: 'sum',
 });

The following series chart types are supported with combination charts:

  • Line (chartType: 'line')
  • Area (chartType: 'Area')
  • Stacked Area (chartType: 'stackedArea')
  • Grouped Column (chartType: 'groupedColumn')
  • Stacked Column (chartType: 'stackedColumn')

Note that only line and area series chart types can be plotted against a secondary axis.

The following example demonstrates the above configuration, note the following:

  • The 'Rain' series uses a groupedColumn chart type and is plotted against the primary Y axis (secondaryAxis=false)
  • 'Pressure' and 'Temp' use a line chart type and are plotted against separate secondary Y axes (secondaryAxis=true)
  • Values are aggregated by the 'Month' category by setting aggFunc: 'sum'
  • Chart Ranges are hidden using suppressChartRanges=true

Range Chart API

Range Charts can be created programmatically using:

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

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 *
ChartParamsCellRange
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 column contents 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: ChartParamsCellRange;

type ChartParamsCellRange = 
      Partial<Omit<CellRangeParams, 'rowStartPinned' 
    | 'rowEndPinned'>>


interface CellRangeParams {
  // Start row index 
  rowStartIndex: number | null;
  // Pinned state of start row. Either 'top', 'bottom' or null 
  rowStartPinned?: RowPinnedType;
  // End row index 
  rowEndIndex: number | null;
  // Pinned state of end row. Either 'top', 'bottom' or null 
  rowEndPinned?: RowPinnedType;
  // 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)[];
}

type RowPinnedType = 
      'top' 
    | 'bottom' 
    | null 
    | undefined
chartType *
ChartType
The type of chart to create. 
chartType: ChartType;

type ChartType = 
      'column' 
    | 'groupedColumn' 
    | 'stackedColumn' 
    | 'normalizedColumn' 
    | 'bar' 
    | 'groupedBar' 
    | 'stackedBar' 
    | 'normalizedBar' 
    | 'line' 
    | 'scatter' 
    | 'bubble' 
    | 'pie' 
    | 'doughnut' 
    | 'area' 
    | 'stackedArea' 
    | 'normalizedArea' 
    | 'histogram' 
    | 'columnLineCombo' 
    | 'areaColumnCombo' 
    | 'customCombo'
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
string | IAggFunc
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<TData = any, TValue = any> {
    (params: IAggFuncParams<TData, TValue>) : any
}

interface IAggFuncParams<TData = any, TValue = any> {
  // Values to aggregate 
  values: TValue[];
  // Column the aggregation function is working on 
  column: Column;
  // ColDef of the aggregation column 
  colDef: ColDef<TData>;
  // Pivot Result Column being produced using this aggregation 
  pivotResultColumn?: Column;
  // The parent RowNode, where the aggregation result will be shown 
  rowNode: IRowNode<TData>;
  // data (if any) of the parent RowNode 
  data: TData;
  // The grid api. 
  api: GridApi<TData>;
  // The column api. 
  columnApi: ColumnApi;
  // Application context as set on `gridOptions.context`. 
  context: any;
}
seriesChartTypes
SeriesChartType[]
The series chart type configurations used in combination charts 
seriesChartTypes: SeriesChartType[];

interface SeriesChartType {
  colId: string;
  chartType: ChartType;
  secondaryAxis?: boolean;
}

type ChartType = 
      'column' 
    | 'groupedColumn' 
    | 'stackedColumn' 
    | 'normalizedColumn' 
    | 'bar' 
    | 'groupedBar' 
    | 'stackedBar' 
    | 'normalizedBar' 
    | 'line' 
    | 'scatter' 
    | 'bubble' 
    | 'pie' 
    | 'doughnut' 
    | 'area' 
    | 'stackedArea' 
    | 'normalizedArea' 
    | 'histogram' 
    | 'columnLineCombo' 
    | 'areaColumnCombo' 
    | 'customCombo'
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
HTMLElement
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
AgChartThemeOverrides
Allows specific chart options in the current theme to be overridden. See Overriding Existing Themes.
chartThemeOverrides: AgChartThemeOverrides;

interface AgChartThemeOverrides {
}
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.

Next Up

Continue to the next section to learn about the: Pivot Chart API.