{"id":10481,"library":"ag-charts-react","title":"AG Charts React Component","description":"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.","status":"active","version":"13.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/ag-grid/ag-charts","tags":["javascript","react","charts","graphs","chart","graph","data","react charts","react graphs","typescript"],"install":[{"cmd":"npm install ag-charts-react","lang":"bash","label":"npm"},{"cmd":"yarn add ag-charts-react","lang":"bash","label":"yarn"},{"cmd":"pnpm add ag-charts-react","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for the React component to function.","package":"react","optional":false}],"imports":[{"note":"`AgChartsReact` is a named export. The CommonJS `require` syntax is generally not recommended for modern React/ESM projects.","wrong":"import AgChartsReact from 'ag-charts-react';\nconst AgChartsReact = require('ag-charts-react');","symbol":"AgChartsReact","correct":"import { AgChartsReact } from 'ag-charts-react';"},{"note":"Import types using `import type` for better tree-shaking and to explicitly distinguish them from runtime values. `AgChartOptions` is a named type export.","wrong":"import { AgChartOptions } from 'ag-charts-react';\nimport AgChartOptions from 'ag-charts-react';","symbol":"AgChartOptions","correct":"import type { AgChartOptions } from 'ag-charts-react';"},{"note":"Import `AgChartInstance` as a type for accessing the chart's imperative API via a React ref. It is also a named type export.","wrong":"import { AgChartInstance } from 'ag-charts-react';","symbol":"AgChartInstance","correct":"import type { AgChartInstance } from 'ag-charts-react';"}],"quickstart":{"code":"import React, { useState, useRef, useEffect } from 'react';\nimport { AgChartsReact } from 'ag-charts-react';\nimport type { AgChartOptions, AgChartInstance } from 'ag-charts-react';\n\nconst ChartExample: React.FC = () => {\n  const chartRef = useRef<AgChartInstance | null>(null);\n  const [options, setOptions] = useState<AgChartOptions>({\n    data: [\n      { month: 'Jan', avgTemp: 2.3, iceCreamSales: 162000 },\n      { month: 'Mar', avgTemp: 6.3, iceCreamSales: 302000 },\n      { month: 'May', avgTemp: 16.2, iceCreamSales: 800000 },\n      { month: 'Jul', avgTemp: 22.8, iceCreamSales: 1254000 },\n      { month: 'Sep', avgTemp: 14.5, iceCreamSales: 950000 },\n      { month: 'Nov', avgTemp: 8.9, iceCreamSales: 200000 },\n    ],\n    series: [\n      {\n        type: 'bar',\n        xKey: 'month',\n        yKey: 'iceCreamSales',\n        yName: 'Ice Cream Sales',\n      },\n      {\n        type: 'line',\n        xKey: 'month',\n        yKey: 'avgTemp',\n        yName: 'Average Temperature',\n        marker: { enabled: true },\n        strokeWidth: 3,\n        axes: 'secondary-y-axis',\n      },\n    ],\n    axes: [\n      { type: 'category', position: 'bottom' },\n      { type: 'number', position: 'left', title: { text: 'Sales' } },\n      {\n        type: 'number',\n        position: 'right',\n        id: 'secondary-y-axis',\n        title: { text: 'Temperature (°C)' },\n      },\n    ],\n    title: { text: 'Ice Cream Sales vs. Average Temperature' },\n    subtitle: { text: '(Monthly Data)' },\n    legend: { enabled: true },\n  });\n\n  useEffect(() => {\n    // Example of programmatic API interaction after mount\n    if (chartRef.current) {\n      console.log('Chart instance available:', chartRef.current);\n      // You could call chartRef.current.download('my-chart.png') here for example\n    }\n  }, []);\n\n  return (\n    <div style={{ height: '500px', width: '100%' }}>\n      <AgChartsReact ref={chartRef} options={options} />\n    </div>\n  );\n};\n\nexport default ChartExample;\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=13.0.0"},{"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 */ }`.","message":"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.","severity":"breaking","affected_versions":">=13.0.0"},{"fix":"Ensure your project uses React version `^18.0.0 || ^19.0.0` to satisfy the peer dependency requirements. Upgrade React if necessary.","message":"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.","severity":"breaking","affected_versions":"<18.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=12.0.0 <13.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Uncaught ReferenceError: exports is not defined"},{"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.","cause":"The `options` object or its required nested properties (`data`, `series`) are `undefined` or malformed when passed to `AgChartsReact`.","error":"TypeError: Cannot read properties of undefined (reading 'series') (or similar for other options properties like 'data', 'axes')"},{"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).","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.","error":"AG Charts - unable to resolve global window"}],"ecosystem":"npm"}