AG Charts Community Edition

Common errors

• Cannot read properties of null (reading 'appendChild')

  cause The HTML element specified in `container` option either does not exist or has not been rendered to the DOM when `AgCharts.create` is called.
  fix Ensure the container element exists in your HTML and is available in the DOM before calling `agCharts.AgCharts.create()`. For example, call it within a `DOMContentLoaded` event listener or a React `useEffect` hook.

• TS2345: Argument of type '{...}' is not assignable to parameter of type 'AgChartOptions'. Object literal may only specify known properties, and 'unknownProperty' does not exist in type 'AgChartOptions'.

  cause You are using an unrecognized or misspelled chart configuration property, or a property that has been removed/renamed in a newer version.
  fix Double-check your chart options against the official AG Charts documentation for your specific version. Pay close attention to property casing and structure, especially after major version upgrades (e.g., to v13).

• TypeError: Cannot read properties of undefined (reading 'create')

  cause The `AgCharts` object is not correctly imported or is undefined, often due to incorrect CommonJS `require` or ES module `import` syntax.
  fix Ensure you are using `import * as agCharts from 'ag-charts-community';` and then calling `agCharts.AgCharts.create(...)`. Avoid `import { AgCharts } from 'ag-charts-community';` as it is not the correct export pattern for the main API object.

Warnings

• breaking Many chart options have been renamed or moved within the options structure. Refer to the official migration guide for a complete list of changes.
  Fix: Review your chart configuration options against the v13 documentation and update paths/names accordingly. For example, `series[].marker` options might have been moved.
• breaking The chart's initial configuration can no longer be updated via `AgCharts.update`. This function is now strictly for updating data or specific mutable properties, not for re-configuring the entire chart definition.
  Fix: If you need to change the fundamental chart configuration, you must recreate the chart instance using `AgCharts.create`. For data and property updates, use `AgCharts.update` with a new options object that maintains the original structure.
• breaking The `highlight-data-points` chart interaction option has been removed, changing how data points are visually emphasized on hover or selection.
  Fix: Remove the `highlight-data-points` option from your chart configurations. Explore alternative interaction options available in v13, or implement custom highlighting logic if necessary.
• breaking For the mini-map navigator, the `label` and `value` fields within `agCharts.miniMap.navigator` are now mandatory fields.
  Fix: Ensure that your `agCharts.miniMap.navigator` configuration explicitly includes both `label` and `value` properties to avoid runtime errors.

Install

• npm install ag-charts-community npm
• yarn add ag-charts-community yarn
• pnpm add ag-charts-community pnpm

Imports

• AgCharts
  wrong:

  import { AgCharts } from 'ag-charts-community';

  correct:

  import * as agCharts from 'ag-charts-community';

  The primary API surface is exposed as a namespace `agCharts` containing the `AgCharts` object. Attempting to destructure `AgCharts` directly is incorrect.
• AgChartOptions
  wrong:

  import { AgChartOptions } from 'ag-charts-community';

  correct:

  import type { AgChartOptions } from 'ag-charts-community';

  Type definitions like `AgChartOptions` should be imported using `import type` for clarity and better tree-shaking, especially in TypeScript projects.
• create
  wrong:

  import { create } from 'ag-charts-community';

  correct:

  import { AgCharts } from 'ag-charts-community'; AgCharts.create({...});

  `create` is a static method on the `AgCharts` object, not a top-level named export. It is used to initialize a new chart instance.

Quickstart

This quickstart initializes a combined line and bar chart displaying monthly weather data (temperature and rainfall) using `ag-charts-community`. It demonstrates basic chart configuration with data, series, axes, and titles, and dynamically creates a DOM container if one doesn't exist.

import * as agCharts from 'ag-charts-community';

const options: agCharts.AgChartOptions = {
    container: document.getElementById('myChart'),
    data: [
        { month: 'Jan', avgTemp: 2, rainfall: 40 },
        { month: 'Feb', avgTemp: 2.3, rainfall: 45 },
        { month: 'Mar', avgTemp: 4.8, rainfall: 50 },
        { month: 'Apr', avgTemp: 7.6, rainfall: 55 },
        { month: 'May', avgTemp: 10.7, rainfall: 60 },
        { month: 'Jun', avgTemp: 13.9, rainfall: 65 },
        { month: 'Jul', avgTemp: 16.2, rainfall: 70 },
        { month: 'Aug', avgTemp: 15.9, rainfall: 75 },
        { month: 'Sep', avgTemp: 13.3, rainfall: 80 },
        { month: 'Oct', avgTemp: 9.3, rainfall: 70 },
        { month: 'Nov', avgTemp: 5.7, rainfall: 60 },
        { month: 'Dec', avgTemp: 3.1, rainfall: 50 }
    ],
    series: [
        {
            type: 'line',
            xKey: 'month',
            yKey: 'avgTemp',
            yName: 'Avg Temperature (°C)'
        },
        {
            type: 'bar',
            xKey: 'month',
            yKey: 'rainfall',
            yName: 'Rainfall (mm)'
        }
    ],
    axes: [
        {
            type: 'category',
            position: 'bottom',
            title: { text: 'Month' }
        },
        {
            type: 'number',
            position: 'left',
            keys: ['avgTemp'],
            title: { text: 'Temperature (°C)' }
        },
        {
            type: 'number',
            position: 'right',
            keys: ['rainfall'],
            title: { text: 'Rainfall (mm)' },
            grid: { enabled: false }
        }
    ],
    title: {
        text: 'Monthly Weather Data'
    },
    subtitle: {
        text: 'London, 2023'
    }
};

// Ensure a container element exists for the chart
if (!document.getElementById('myChart')) {
    const chartDiv = document.createElement('div');
    chartDiv.id = 'myChart';
    chartDiv.style.height = '400px';
    chartDiv.style.width = '600px';
    document.body.appendChild(chartDiv);
}

agCharts.AgCharts.create(options);