AG Charts TypeScript Types

13.2.1 verified Sun Apr 19 auth: no javascript

AG Charts is a high-performance, canvas-based charting library for JavaScript and TypeScript, offering extensive customizability and no third-party dependencies for its core functionality. It integrates seamlessly with popular frameworks like React, Angular, and Vue. The `ag-charts-types` package, currently at stable version 13.2.1, provides comprehensive TypeScript type definitions, enabling type-safe development for AG Charts applications. The library maintains a frequent release cadence, delivering continuous improvements and new features across minor and patch versions, with significant breaking changes typically reserved for major version bumps. Its key differentiators include exceptional rendering performance, a highly flexible API for detailed customization, and a robust feature set suitable for enterprise data visualization.

Common errors

error Argument of type 'string' is not assignable to parameter of type 'HTMLElement | undefined'. ↓

cause Attempting to pass a string ID for the chart container, which is no longer supported in recent versions of AG Charts.

fix

Change container: 'myChartId' to container: document.getElementById('myChartId') ?? undefined.

error Property 'create' does not exist on type 'typeof import("ag-charts-community")'. Did you mean 'AgCharts.create'? ↓

cause Incorrect import of `AgCharts` as a named export instead of a namespace import.

fix

Change import { AgCharts } from 'ag-charts-community'; to import * as AgCharts from 'ag-charts-community';.

error Type '{ type: "bar"; xKey: string; yKey: string; }' is not assignable to type 'AgSeriesOptions'. Types of property 'type' are incompatible. Type '"bar"' is not assignable to type '"line" | "area" | "column" | ...'. ↓

cause Using the deprecated `bar` series type after v12.0.0.

fix

Update type: 'bar' to type: 'column' in your series options.

Warnings

breaking In AG Charts v13.0.0, the `container` option for `AgCharts.create` and `AgCharts.update` no longer accepts a string ID. You must provide an actual DOM element. Several styling properties were also renamed or moved (e.g., `axis.label.padding` to `axis.label.spacing`, `tooltip.position.xOffset` to `tooltip.position.x`). ↓

fix Ensure `container` is a `HTMLElement | undefined`. Review the v13 changelog for specific property renames and adapt your chart options accordingly, e.g., `container: document.getElementById('myChart') ?? undefined`.

breaking AG Charts v12.0.0 changed `AgCharts.create` and `AgCharts.update` to return `void` instead of the chart instance. If you need a reference to the chart instance, use `AgCharts.getChart(element)`. ↓

fix Replace `const chart = AgCharts.create(options);` with `AgCharts.create(options); const chart = AgCharts.getChart(options.container);`.

breaking The series type `bar` was renamed to `column` in AG Charts v12.0.0. Using `type: 'bar'` will no longer render a column chart. ↓

fix Update all series configurations using `type: 'bar'` to `type: 'column'`.

gotcha AG Charts typically expects its data array to be an `Array<any>` or a more specific type. Incorrect data structures or missing keys can lead to charts not rendering or displaying unexpected behavior, often silently. ↓

fix Always ensure your `data` array is an array of objects, and that the `xKey`, `yKey`, and other series-specific keys precisely match property names within your data objects. Utilize TypeScript types like `AgChartOptions` to catch data type mismatches at compile-time.

Install

npm install ag-charts-types

yarn add ag-charts-types

pnpm add ag-charts-types

Imports

AgCharts
wrong
```
import { AgCharts } from 'ag-charts-community';
```
correct
```
import * as AgCharts from 'ag-charts-community';
```
AgCharts is typically imported as a namespace to access static methods like `create` and `update`.
AgChartOptions
wrong
```
import type { AgChartOptions } from 'ag-charts-types';
```
correct
```
import { AgChartOptions } from 'ag-charts-community';
```
While `ag-charts-types` provides the definitions, the actual type is re-exported from `ag-charts-community` for direct use. It is also available as a type-only import if preferred.
AgCartesianChartOptions
wrong
```
import { AgCartesianChartOptions } from 'ag-charts-types';
```
correct
```
import { AgCartesianChartOptions } from 'ag-charts-community';
```
Specific chart options like this are also re-exported from the main community package. Use this for type-checking Cartesian charts.
AgLineSeriesOptions
```
import type { AgLineSeriesOptions } from 'ag-charts-community';
```
Specific series options are available as types for detailed configuration. Use 'import type' for clarity and better tree-shaking.

Quickstart

This quickstart demonstrates how to create a basic line chart using AG Charts, displaying sales and profit data over several years with custom styling and axes configuration.

import * as AgCharts from 'ag-charts-community';
import { AgChartOptions } from 'ag-charts-community';

const data = [
  { year: '2020', sales: 1500, profit: 800 },
  { year: '2021', sales: 1800, profit: 950 },
  { year: '2022', sales: 2200, profit: 1100 },
  { year: '2023', sales: 2500, profit: 1300 },
];

const options: AgChartOptions = {
  container: document.getElementById('myChart') ?? undefined,
  data: data,
  title: {
    text: 'Sales and Profit by Year',
  },
  subtitle: {
    text: 'Example using AG Charts',
  },
  series: [
    {
      type: 'line',
      xKey: 'year',
      yKey: 'sales',
      yName: 'Sales',
      stroke: '#007bff',
      marker: {
        enabled: true,
      },
    },
    {
      type: 'line',
      xKey: 'year',
      yKey: 'profit',
      yName: 'Profit',
      stroke: '#28a745',
      marker: {
        enabled: true,
      },
    },
  ],
  axes: [
    {
      type: 'category',
      position: 'bottom',
      title: {
        text: 'Year',
      },
    },
    {
      type: 'number',
      position: 'left',
      title: {
        text: 'Amount',
      },
    },
  ],
};

// Ensure the container exists in your HTML: <div id="myChart" style="height: 400px; width: 600px;"></div>
AgCharts.create(options);