AG Charts React Component

Common errors

• Uncaught ReferenceError: exports is not defined

  cause This error often occurs in older bundler setups (like certain Create React App configurations) when `ag-charts-react` or its dependencies are treated as CommonJS modules in an environment expecting ESM, or vice-versa.
  fix If using an older Create React App setup, ensure your bundler is correctly configured to handle ESM modules. Sometimes, using `--force` or `--legacy-peer-deps` during installation might resolve immediate issues, but a proper bundler configuration for ESM is preferred.

• TypeError: Cannot read properties of undefined (reading 'series') (or similar for other options properties like 'data', 'axes')

  cause The `options` object or its required nested properties (`data`, `series`) are `undefined` or malformed when passed to `AgChartsReact`.
  fix Verify that your `options` object is correctly initialized and contains at least `data` (an array of objects) and `series` (an array of series definitions), as shown in the quickstart. Ensure all `xKey` and `yKey` values correctly map to properties in your `data` objects.

• AG Charts - unable to resolve global window

  cause This error typically indicates that AG Charts is being initialized in a server-side rendering (SSR) or Node.js environment where the global `window` object is not available.
  fix For SSR frameworks like Next.js, ensure that `AgChartsReact` components are rendered only on the client-side. You can achieve this using dynamic imports with `ssr: false` or by conditionally rendering the component after the component mounts (e.g., within a `useEffect` hook).

Warnings

• breaking AG Charts v13.0.0 introduced significant changes to axis configuration, making the `axes` option a dictionary instead of an array. It also simplified secondary axis setup and removed the `axes.keys` option, relying instead on `series._KeyAxes` properties.
  Fix: Update your `axes` configuration from an array to an object (dictionary) using default keys ('x', 'y') or custom IDs. Use `series._KeyAxes` to link series to specific axes. Refer to the v13 migration guide for full details.
• breaking AG Charts v13.0.0 changed how themes are applied when creating custom themes. The `theme` option now requires a `baseTheme` property to inherit from an existing theme, rather than directly specifying the base theme name.
  Fix: If creating custom themes, update your theme definition to include `baseTheme` within the `theme` object. For example, `{ theme: { baseTheme: 'ag-default', /* ... overrides */ } }` instead of `{ theme: 'ag-default', /* ... overrides */ }`.
• breaking AG Charts requires React 18 or newer as a peer dependency. Using older versions of React (e.g., React 17) might lead to installation issues or unexpected runtime behavior, even if it might 'work' with `--force` flags.
  Fix: Ensure your project uses React version `^18.0.0 || ^19.0.0` to satisfy the peer dependency requirements. Upgrade React if necessary.
• gotcha The `options` prop passed to `AgChartsReact` is expected to be an immutable object for optimal performance and correct reactivity. Mutating the `options` object directly will not trigger chart updates; instead, a new `options` object must be provided to React's state management.
  Fix: Always update the chart options by creating a *new* object (e.g., using `setOptions` with a spread operator or `useMemo`) when properties within the `options` object change. Avoid direct mutation of `options` or its nested properties.
• breaking AG Charts v12.0.0 introduced several breaking changes including the removal of deprecated properties like `zoom.minVisibleItemsX/Y`, `tooltip.position.type`, and changes to `contextMenu.extraActions`. It also leveraged TypeScript Generics for improved type safety and developer experience.
  Fix: Review the v12 migration guide for specific changes to the `options` structure related to zoom, tooltips, and context menus. Update property names and structures accordingly.

Install

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

Imports

• AgChartsReact
  wrong:

  import AgChartsReact from 'ag-charts-react';
  const AgChartsReact = require('ag-charts-react');

  correct:

  import { AgChartsReact } from 'ag-charts-react';

  `AgChartsReact` is a named export. The CommonJS `require` syntax is generally not recommended for modern React/ESM projects.
• AgChartOptions
  wrong:

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

  correct:

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

  Import types using `import type` for better tree-shaking and to explicitly distinguish them from runtime values. `AgChartOptions` is a named type export.
• AgChartInstance
  wrong:

  import { AgChartInstance } from 'ag-charts-react';

  correct:

  import type { AgChartInstance } from 'ag-charts-react';

  Import `AgChartInstance` as a type for accessing the chart's imperative API via a React ref. It is also a named type export.

Quickstart

Initializes and renders a combination bar and line chart using `AgChartsReact`. It demonstrates defining data, multiple series, dual axes, basic styling, and accessing the chart instance via a ref.

import React, { useState, useRef, useEffect } from 'react';
import { AgChartsReact } from 'ag-charts-react';
import type { AgChartOptions, AgChartInstance } from 'ag-charts-react';

const ChartExample: React.FC = () => {
  const chartRef = useRef<AgChartInstance | null>(null);
  const [options, setOptions] = useState<AgChartOptions>({
    data: [
      { month: 'Jan', avgTemp: 2.3, iceCreamSales: 162000 },
      { month: 'Mar', avgTemp: 6.3, iceCreamSales: 302000 },
      { month: 'May', avgTemp: 16.2, iceCreamSales: 800000 },
      { month: 'Jul', avgTemp: 22.8, iceCreamSales: 1254000 },
      { month: 'Sep', avgTemp: 14.5, iceCreamSales: 950000 },
      { month: 'Nov', avgTemp: 8.9, iceCreamSales: 200000 },
    ],
    series: [
      {
        type: 'bar',
        xKey: 'month',
        yKey: 'iceCreamSales',
        yName: 'Ice Cream Sales',
      },
      {
        type: 'line',
        xKey: 'month',
        yKey: 'avgTemp',
        yName: 'Average Temperature',
        marker: { enabled: true },
        strokeWidth: 3,
        axes: 'secondary-y-axis',
      },
    ],
    axes: [
      { type: 'category', position: 'bottom' },
      { type: 'number', position: 'left', title: { text: 'Sales' } },
      {
        type: 'number',
        position: 'right',
        id: 'secondary-y-axis',
        title: { text: 'Temperature (°C)' },
      },
    ],
    title: { text: 'Ice Cream Sales vs. Average Temperature' },
    subtitle: { text: '(Monthly Data)' },
    legend: { enabled: true },
  });

  useEffect(() => {
    // Example of programmatic API interaction after mount
    if (chartRef.current) {
      console.log('Chart instance available:', chartRef.current);
      // You could call chartRef.current.download('my-chart.png') here for example
    }
  }, []);

  return (
    <div style={{ height: '500px', width: '100%' }}>
      <AgChartsReact ref={chartRef} options={options} />
    </div>
  );
};

export default ChartExample;