JavaScript ChartsCreate/Update

Learn about creating and updating charts in more detail.

Creating and Updating Charts

AgCharts exposes a static create() method to perform chart initialisation, and the resulting AgChartInstance has methods such as AgChartInstance.update() to allow updating configuration.

The AgChartOptions type defines the configuration structure. See the Options Reference for more details.

Mutations to the previously used options object are not automatically picked up by the chart implementation. AgChartInstance.update() or AgChartInstance.updateDelta() should be called to apply changes.

We expect the options supplied to AgChartInstance.update() to be the full configuration state for the chart, not a partial configuration. Use AgChartInstance.updateDelta() to apply partial updates.

We expect immutable data for data elements, as this enables efficient change detection. If data elements are mutated in-place, we cannot guarantee to detect the changes.

The following example demonstrates both create and update cases:

  • Definition of an options object used to create the initial chart state.
  • Buttons that invoke mutations of the options and trigger update of the chart state.

Delta Options Update

AgChartInstance exposes the updateDelta() method to allow partial updates to a charts options.

To assist with state management, the complete applied options state can be retrieved by calling the getOptions() method on the AgChartInstance.

The following example demonstrates:

  • Retrieving current Chart configuration via getOptions().
  • Mutation of the Chart configuration via updateDelta().

Waiting for Options Update

Creation and updates happen asynchronously, but in some situations it maybe useful to know when an update has been rendered.

To assist with this, AgChartInstance.update() and AgChartInstance.updateDelta() return Promises that resolve once rendering is complete.

Additionally AgChartsInstance.waitForUpdate() can be used after initial creation to understand when the first rendering of the newly created chart is complete.

Promises do not take animations into account, they resolve after the first rendering in an animation sequence.

This example demonstrates how this can be used to create trivial loops to continuously update a chart, with each update only being applied once the previous update has completed.

Destroying Charts

Charts can be destroyed by using the AgChartInstance.destroy() method.