---
title: "Create/Update"
framework: javascript
version: "14.1.0"
---

# Create/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](https://www.ag-grid.com/charts/options/) 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.

> **Note**
>
> 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.

> **Warning**
>
> We expect immutable data for `data` elements and `theme` options, as this enables efficient change detection. If `data` elements or `theme` options are mutated in-place, we cannot guarantee to detect the changes.

#### AgCharts

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| create | Function |  | Create a new `AgChartInstance` based upon the given configuration options. |
| createFinancialChart | Function |  | Create a new `AgChartInstance` based upon the given configuration options. |
| createGauge | Function |  | Create a new `AgChartInstance` based upon the given configuration options. |

#### AgChartInstance

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| update | Function |  | Update an existing `AgChartInstance`. Options provided should be complete and not partial.  Returns a `Promise` that resolves once the requested change has been rendered.  __Note:__ As each call could trigger a chart redraw, multiple calls in quick succession could result in undesirable flickering. Callers should batch up and/or debounce changes to avoid unintended partial update renderings. |
| updateDelta | Function |  | Update an existing `AgChartInstance` by applying a partial set of option changes.  Returns a `Promise` that resolves once the requested change has been rendered.  __Note:__ As each call could trigger a chart redraw, each individual delta options update should leave the chart in a valid options state.  Also, multiple calls in  quick succession could result in undesirable flickering. Callers should batch up and/or debounce changes to avoid unintended partial update renderings. |
| getOptions | Function |  | Get the `AgChartOptions` representing the current chart configuration. |
| applyTransaction | Function |  | Apply a transaction to incrementally update the chart data without replacing the entire dataset.  Returns a `Promise` that resolves once the transaction has been applied and rendered |
| waitForUpdate | Function |  | Returns a `Promise` that resolves once any pending changes have been rendered. |
| download | Function |  | Starts a browser-based image download for the given `AgChartInstance`.  Returns a `Promise` that resolves once the download has been initiated. |
| getImageDataURL | Function |  | Returns a base64-encoded image data URL for the given `AgChartInstance`. |
| getState | Function |  | Returns a representation of the current state of the given `AgChartInstance`. |
| setState | Function |  | Sets the state of the given `AgChartInstance` to the state provided. |
| getSelection | Function |  | Retrieve the current selection. An error may be thrown if the chart state mutates whilst the selection items are being iterated.  Returns An iterable of all selected items. |
| setSelection | Function |  | Replaces the current selection. |
| clearSelection | Function |  | Clear the entire selection state of all items on all series. |
| destroy | Function |  | Destroy the chart instance and any allocated resources supporting its rendering. |

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.

#### Create and Update with AgChartOptions

```ts
import {
  AgAreaSeriesOptions,
  AgChartLegendPosition,
  AgChartOptions,
  AgCharts,
  AreaSeriesModule,
  CategoryAxisModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-community";
import { getData } from "./data";

function buildSeries(name: string): AgAreaSeriesOptions {
  return {
    type: "area",
    xKey: "year",
    yKey: name.toLowerCase(),
    yName: name,
    fillOpacity: 0.5,
  };
}
const series = [
  buildSeries("IE"),
  buildSeries("Chrome"),
  buildSeries("Firefox"),
  buildSeries("Safari"),
];
const positions: AgChartLegendPosition[] = ["left", "top", "right", "bottom"];
const legend = {
  position: positions[1],
};
ModuleRegistry.registerModules([
  AreaSeriesModule,
  CategoryAxisModule,
  LegendModule,
  NumberAxisModule,
]);

const options: AgChartOptions = {
  title: {
    text: "Browser Usage Statistics",
  },
  subtitle: {
    text: "2009-2019",
  },
  data: getData(),
  series,
  legend,
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

function reverseSeries() {
  options.series = series.reverse();

  chart.update(options);
}

function swapTitles() {
  const oldTitle = options.title;
  options.title = options.subtitle;
  options.subtitle = oldTitle;

  chart.update(options);
}

function rotateLegend() {
  const currentIdx = positions.indexOf(legend.position ?? "top");
  legend.position = positions[(currentIdx + 1) % positions.length];
  options.legend = legend;

  chart.update(options);
}

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).reverseSeries = reverseSeries;
  (<any>window).swapTitles = swapTitles;
  (<any>window).rotateLegend = rotateLegend;
}
```

[Live example: Create and Update with AgChartOptions](https://www.ag-grid.com/charts/typescript/api-create-update/examples/create-update)

## 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`.

> **Warning**
>
> When updating `series` or `axes` options, the complete array must be supplied with all the properties for each item.

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| updateDelta | Function |  | Update an existing `AgChartInstance` by applying a partial set of option changes.  Returns a `Promise` that resolves once the requested change has been rendered.  __Note:__ As each call could trigger a chart redraw, each individual delta options update should leave the chart in a valid options state.  Also, multiple calls in  quick succession could result in undesirable flickering. Callers should batch up and/or debounce changes to avoid unintended partial update renderings. |
| getOptions | Function |  | Get the `AgChartOptions` representing the current chart configuration. |

The following example demonstrates:

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

#### Update with Partial AgChartOptions

```ts
import {
  AgAreaSeriesOptions,
  AgChartLegendPosition,
  AgChartOptions,
  AgChartTheme,
  AgCharts,
  AreaSeriesModule,
  CategoryAxisModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-community";
import { getData } from "./data";

function buildSeries(name: string): AgAreaSeriesOptions {
  return {
    type: "area",
    xKey: "year",
    yKey: name.toLowerCase(),
    yName: name,
    fillOpacity: 0.5,
  };
}
const series = [
  buildSeries("IE"),
  buildSeries("Chrome"),
  buildSeries("Firefox"),
  buildSeries("Safari"),
];
const positions: AgChartLegendPosition[] = ["left", "top", "right", "bottom"];
const legend = {
  position: positions[1],
};
ModuleRegistry.registerModules([
  AreaSeriesModule,
  LegendModule,
  CategoryAxisModule,
  NumberAxisModule,
]);

const options: AgChartOptions = {
  title: {
    text: "Browser Usage Statistics",
  },
  subtitle: {
    text: "2009-2019",
  },
  data: getData(),
  series,
  legend,
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

function reverseSeries() {
  const series = chart.getOptions().series as AgAreaSeriesOptions[];
  series!.reverse();
  chart.updateDelta({ series });
}

function swapTitles() {
  const { title, subtitle } = chart.getOptions();
  chart.updateDelta({ title: subtitle, subtitle: title });
}

function rotateLegend() {
  const position = chart.getOptions().legend!.position;
  const currentIdx = positions.indexOf(position ?? "top");
  const newPosition = positions[(currentIdx + 1) % positions.length];
  chart.updateDelta({ legend: { position: newPosition } });
}

function changeTheme() {
  const theme = chart.getOptions()?.theme as AgChartTheme;
  const markersEnabled =
    theme?.overrides?.area?.series?.marker?.enabled ?? false;
  chart.updateDelta({
    theme: {
      overrides: { area: { series: { marker: { enabled: !markersEnabled } } } },
    },
  });
}

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).reverseSeries = reverseSeries;
  (<any>window).swapTitles = swapTitles;
  (<any>window).rotateLegend = rotateLegend;
  (<any>window).changeTheme = changeTheme;
}
```

[Live example: Update with Partial AgChartOptions](https://www.ag-grid.com/charts/typescript/api-create-update/examples/update-partial)

## Waiting for Options Update

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

To assist with this, `AgChartInstance.update()` and `AgChartInstance.updateDelta()` return `Promise`s 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.

> **Note**
>
> Although rendering may be complete, browsers may not repaint until Javascript execution pauses.
>
> `Promise`s do not take animations into account, they resolve after the first rendering in an animation sequence.

This example demonstrates how these APIs can be used to continuously update a chart, with each update only being applied once the previous update has been rendered.

#### Wait for Options Update

```ts
import {
  AgCharts,
  AllCommunityModule,
  ModuleRegistry,
} from "ag-charts-community";

ModuleRegistry.registerModules(AllCommunityModule);

const options = {
  title: { text: "Frameworks not supported" },
  subtitle: { text: "Switch to Javascript" },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);
```

[Live example: Wait for Options Update](https://www.ag-grid.com/charts/typescript/api-create-update/examples/wait-for-update)

## Destroying Charts

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

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| destroy | Function |  | Destroy the chart instance and any allocated resources supporting its rendering. |