AG Charts Core Library

Common errors

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

  cause The `container` element provided in the chart options does not exist or is `null` when `AgCharts.create` is called.
  fix Verify that `document.getElementById('your-container-id')` returns a valid HTML element. Ensure the DOM is fully loaded before chart initialization.

• AgCharts.create(container, options) is no longer supported. Please use AgCharts.create({ container, ...options }).

  cause Attempting to use the legacy two-argument signature for `AgCharts.create` after upgrading to version 13.0.0 or later.
  fix Update `AgCharts.create` calls to use the single options object format: `AgCharts.create({ container: myContainerElement, data: myData, ...otherOptions })`.

• Property 'fillOpacity' does not exist on type 'AgLineSeriesOptions'.

  cause Using deprecated `fillOpacity` or `strokeOpacity` properties directly on series options after upgrading to v13.0.0+. These properties were removed in favor of setting opacity directly in the color string.
  fix Remove `fillOpacity` and `strokeOpacity`. Integrate opacity into the `fill` and `stroke` color values, e.g., `'rgba(255,0,0,0.5)'` or `'#FF000080'`.

Warnings

• breaking The `AgCharts.create` function signature changed in v13.0.0. It now expects a single options object containing all configuration, including the `container` element, instead of `(container, options)` as two separate arguments.
  Fix: Refactor calls from `AgCharts.create(myContainer, myOptions)` to `AgCharts.create({ container: myContainer, ...myOptions })`.
• breaking Properties `series.fillOpacity` and `series.strokeOpacity` were deprecated in v13.0.0. Opacity should now be set directly within the `fill` or `stroke` color strings (e.g., `'#ff000080'`) or by using an `rgba()` function.
  Fix: Remove `fillOpacity` and `strokeOpacity` properties. Adjust `fill` and `stroke` color values to include alpha transparency, e.g., `'rgba(255, 0, 0, 0.5)'`.
• gotcha The `container` element passed to `AgCharts.create` (within the options object) must be a valid HTML element that exists in the DOM when the chart is created. If the element is not found or is `null`, chart rendering will fail silently or throw an error.
  Fix: Ensure the chart container element is present in the DOM before calling `AgCharts.create`. Use `document.getElementById()` or similar methods after `DOMContentLoaded` or a React/Angular lifecycle hook.
• breaking Many internal chart properties and their structures were refactored in v13.0.0. Relying on direct access to internal, undocumented properties may lead to breaking changes during minor or patch updates.
  Fix: Adhere strictly to the documented API for chart configuration and interaction. Avoid accessing private or internal properties unless explicitly advised by AG Charts documentation.

Install

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

Imports

• AgCharts
  wrong:

  const AgCharts = require('ag-charts-core');

  correct:

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

  Primarily designed for ESM environments; CommonJS `require` is not recommended due to module structure and TypeScript support.
• AgChartOptions

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

  Essential TypeScript interface for defining chart configurations. Strongly recommended for type safety.
• AgChartTheme

  import { AgChartTheme } from 'ag-charts-core';

  Used for advanced custom theming of charts to maintain consistent styling across applications.

Quickstart

Initializes and renders a simple column and line chart displaying annual company spending and profit data using `AgCharts.create`.

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

interface DataItem {
  year: number;
  spending: number;
  profit: number;
}

const data: DataItem[] = [
  { year: 2020, spending: 1200, profit: 800 },
  { year: 2021, spending: 1500, profit: 950 },
  { year: 2022, spending: 1300, profit: 850 },
  { year: 2023, spending: 1700, profit: 1100 }
];

function createPerformanceChart() {
  const chartOptions = {
    container: document.getElementById('myChart') as HTMLElement,
    data: data,
    title: {
      text: 'Annual Company Performance',
    },
    subtitle: {
      text: 'Spending vs. Profit Analysis',
    },
    series: [
      {
        type: 'column',
        xKey: 'year',
        yKey: 'spending',
        yName: 'Spending',
        fill: '#5BC0DE',
        stroke: '#428BCA'
      },
      {
        type: 'line',
        xKey: 'year',
        yKey: 'profit',
        yName: 'Profit',
        stroke: '#F0AD4E',
        marker: {
          enabled: true,
          fill: '#F0AD4E'
        }
      }
    ],
    axes: [
      {
        type: 'category',
        position: 'bottom',
        title: {
          text: 'Year'
        }
      },
      {
        type: 'number',
        position: 'left',
        title: {
          text: 'Amount ($)'
        }
      }
    ]
  };

  AgCharts.create(chartOptions);
}

// Simulate DOMContentLoaded for demonstration purposes in a non-browser environment.
// In a browser, ensure this runs after the DOM is fully loaded.
if (typeof document !== 'undefined') {
  document.addEventListener('DOMContentLoaded', () => {
    let container = document.getElementById('myChart');
    if (!container) {
      container = document.createElement('div');
      container.id = 'myChart';
      container.style.width = '700px';
      container.style.height = '400px';
      document.body.appendChild(container);
    }
    createPerformanceChart();
  });
}