AG Charts React Component

13.2.1 verified Sun Apr 19 auth: no javascript

AG Charts React is a high-performance, canvas-based charting library for React applications. It offers a comprehensive set of 30+ chart types, including common visualizations like bar, line, area, and pie charts, as well as specialized types such as financial charts and maps (some advanced features are part of the Enterprise version). The library prioritizes outstanding performance, especially with large datasets and high-frequency updates, and boasts no third-party runtime dependencies, minimizing bundle size and potential conflicts. The current stable version is 13.2.1, with frequent patch and minor releases, and major versions typically introducing significant API or feature enhancements. Key differentiators include its performance, native React integration, comprehensive feature set (split between Community and Enterprise), and a focus on enterprise application development.

Common errors

error 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.

error 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.

error 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

yarn add ag-charts-react

pnpm add ag-charts-react

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;