Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AgChartsReact
✓ import { AgChartsReact } from 'ag-charts-react';
✗ import AgChartsReact from 'ag-charts-react';
const AgChartsReact = require('ag-charts-react');
`AgChartsReact` is a named export. The CommonJS `require` syntax is generally not recommended for modern React/ESM projects.
AgChartOptions
✓ import type { AgChartOptions } from 'ag-charts-react';
✗ import { AgChartOptions } from 'ag-charts-react';
import 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
✓ import type { AgChartInstance } from 'ag-charts-react';
✗ import { 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.
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;
Debug
Known issues
breakingAG 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.fixUpdate 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. affects: >=13.0.0
breakingAG 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.fixIf 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 */ }`. affects: >=13.0.0
breakingAG 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.fixEnsure your project uses React version `^18.0.0 || ^19.0.0` to satisfy the peer dependency requirements. Upgrade React if necessary.
affects: <18.0.0
gotchaThe `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.fixAlways 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.
affects: >=1.0.0
breakingAG 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.fixReview the v12 migration guide for specific changes to the `options` structure related to zoom, tooltips, and context menus. Update property names and structures accordingly.
affects: >=12.0.0 <13.0.0
Errors
Common errors & fixes
Uncaught ReferenceError: exports is not defined
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.
fixIf 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')
The `options` object or its required nested properties (`data`, `series`) are `undefined` or malformed when passed to `AgChartsReact`.
fixVerify 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
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.
fixFor 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).
Audit
Dependencies
reactrequiredRequired peer dependency for the React component to function.