Framework:Javascript Data GridAngular Data GridReact Data GridVue Data Grid

React Data Grid: Chart Events

There are several events which are raised at different points in the lifecycle of a chart.

ChartCreated

The ChartCreated event is raised whenever a chart is first created.

Properties available on the ChartCreated interface.

type
string
Will always be chartCreated.
chartId
string
Id of the created chart. This can later be used to reference the chart via api methods.
api
GridApi
columnApi
ColumnApi

ChartRangeSelectionChanged

This is raised any time that the data range used to render the chart from is changed, e.g. by using the range selection handle or by making changes in the Data tab of the configuration sidebar. This event contains a cellRange object that gives you information about the range, allowing you to recreate the chart.

Properties available on the ChartRangeSelectionChanged interface.

type
string
Will always be chartRangeSelectionChanged.
chartId
string
Id of the effected chart.
id
string
Same as chartId.
cellRange
CellRangeParams
New cellRange selected.
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)[];
}
api
GridApi
columnApi
ColumnApi

ChartOptionsChanged

Formatting changes made by users through the Format Panel will raise the ChartOptionsChanged event:

Properties available on the ChartOptionsChanged interface.

type
string
Will always be chartOptionsChanged.
chartId
string
Id of the effected chart.
chartType
ChartType
chartThemeName
string
Chart theme name of currently selected theme.
chartOptions
ChartOptions<any>
Chart options.
chartOptions: ChartOptions<any>;

interface ChartOptions {
  document?: Document;
  seriesDefaults: T;
  width?: number;
  height?: number;
  padding: PaddingOptions;
  background: BackgroundOptions;
  title: CaptionOptions;
  subtitle: CaptionOptions;
  navigator: NavigatorOptions;
  legend: LegendOptions;
  tooltip?: ChartTooltip;
  listeners?: {[key in string]: Function};
}

interface PaddingOptions {
  top: number;
  right: number;
  bottom: number;
  left: number;
}

interface BackgroundOptions {
  fill: string;
  visible: boolean;
}

interface CaptionOptions {
  enabled: boolean;
  text?: string;
  fontStyle: FontStyle;
  fontWeight: FontWeight;
  fontSize: number;
  fontFamily: string;
  color: string;
}

type FontStyle = 
      'normal' 
    | 'italic' 
    | 'oblique'


type FontWeight = 
      'normal' 
    | 'bold' 
    | 'bolder' 
    | 'lighter' 
    | '100' 
    | '200' 
    | '300' 
    | '400' 
    | '500' 
    | '600' 
    | '700' 
    | '800' 
    | '900'


interface NavigatorOptions {
  enabled: boolean;
  height: number;
  min: number;
  max: number;
  mask: NavigatorMaskOptions;
  minHandle: NavigatorHandleOptions;
  maxHandle: NavigatorHandleOptions;
}

interface NavigatorMaskOptions {
  fill: string;
  stroke: string;
  strokeWidth: number;
  fillOpacity: number;
}

interface NavigatorHandleOptions {
  fill: string;
  stroke: string;
  strokeWidth: number;
  width: number;
  height: number;
  gripLineGap: number;
  gripLineLength: number;
}

interface LegendOptions {
  enabled: boolean;
  position: LegendPosition;
  spacing: number;
  item: LegendItemOptions;
}

enum LegendPosition {
  Top = 'top'
  Right = 'right'
  Bottom = 'bottom'
  Left = 'left'
}

interface LegendItemOptions {
  label: LegendLabelOptions;
  marker: LegendMarkerOptions;
  paddingX: number;
  paddingY: number;
}

interface LegendLabelOptions {
  fontStyle: FontStyle;
  fontWeight: FontWeight;
  fontSize: number;
  fontFamily: string;
  color: string;
}

interface LegendMarkerOptions {
  shape: MarkerShape;
  size: number;
  padding: number;
  strokeWidth: number;
}

type MarkerShape = 
      'circle' 
    | 'cross' 
    | 'diamond' 
    | 'plus' 
    | 'square' 
    | 'triangle'


interface ChartTooltip {
  enabled?: boolean;
  class?: string;
  tracking?: boolean;
  delay?: number;
}
api
GridApi
columnApi
ColumnApi

Here the chartThemeName will be set to the name of the currently selected theme, which will be either one of the Provided Themes or a Custom Theme if used.

ChartDestroyed

This is raised when a chart is destroyed.

Properties available on the ChartDestroyed interface.

type
string
Will always be chartDestroyed.
chartId
string
Id of the effected chart.
api
GridApi
columnApi
ColumnApi

Example: Chart Events

The following example demonstrates when the described events occur by writing to the console whenever they are triggered. Try the following:

  • Create a chart from selection, for example, select a few cells in the "Month" and "Sunshine" columns and right-click to "Chart Range" as a "Line" chart. Notice that a "Created chart with ID id-xxxxxxxxxxxxx" message has been logged to the console.
  • Shrink or expand the selection by a few cells to see the "Changed range selection of chart with ID id-xxxxxxxxxxxx" logged.
  • Click the hamburger icon inside the chart dialog to show chart settings and switch to a column chart. Notice that a "Changed options of chart with ID id-xxxxxxxxxxxxx" message has been logged to the console.
  • Close the chart dialog to see the "Destroyed chart with ID id-xxxxxxxxxxx" message logged.
// Loading...

Accessing Chart Instance

Charts in the grid are produced by the AG Charts library, which is integrated directly into the grid for your convenience. In some advanced use cases, you may wish to access the chart instance that is produced by AG Charts, in order to interact with the chart directly.

The chart instance can be obtained from the chartRef using the getChartRef(chartId) API.

getChartRef
Function
Returns the ChartRef using the supplied chartId.
getChartRef = (chartId: string) => 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;
}

Here is the implementation:

function onChartCreated(event) {
    const chartRef = gridOptions.api.getChartRef(event.chartId);
    const chart = chartRef.chart;
}

Note in the snippet above, the chartId is obtained from the ChartCreated event which is supplied to the onChartCreated callback. The chartId is provided in all chart events.

The example below shows how the chart instance can be used, creating a subtitle and updating it dynamically as you change the range selection.

Other Resources

To learn about series events refer to the standalone charting library documentation.