npmWeb Frontendupdated 08 Aug 2026

ag-charts-types

Item: ag-charts-types
Rating: 3.5
Author: Keyoor

ag-charts-types is the shared TypeScript contract for AG Charts, not the library that draws charts. It exports the option, series, axis, theme, event, callback, state, and chart-instance types consumed by ag-charts-community and ag-charts-enterprise. The package has no dependencies and contains almost no runtime code beyond two tooltip-position enums. Install a matching AG Charts runtime to create a chart; installing this package alone gives JavaScript users no renderer, canvas, components, or AgCharts implementation.

ag-charts-types · v14.1.0 · 3.2M/wk · ★ 477 · pushed 07 Aug 2026 · ag-grid/ag-charts · docs · reviewed by Keyoor

Verdict

Useful infrastructure for wrapper authors, but almost never the package an application should choose directly. Install the matching AG Charts runtime, keep every AG Charts package on the same version, and remember that Enterprise declarations are not an Enterprise license.

API stability2/5The package is a large mirror of the renderer's configuration surface, so every renamed option, new series, callback revision, or axis redesign becomes a public type change. Registry history shows major versions 10 through 14 from July 2024 through June 2026, and the 14.1.0 cartesian contract uses a keyed axes object that rejects older array-based examples. Exact version pins in ag-charts-community confirm that these declarations are intended to move in lockstep with the runtime.

Docs3/5The declaration files are extensive and include useful comments, defaults, callback parameter descriptions, and links to feature references. The official AG Charts site has detailed guides for the renderer. The package's own README is misleading, however: it calls ag-charts-types a canvas charting library and gives runtime-oriented marketing and setup even though the tarball contains contracts rather than a renderer. Direct-install and version-alignment guidance is missing.

Maintenance5/5Version 14.1.0 was published on August 5, 2026, and the repository was pushed on August 7, 2026. The types package is released alongside ag-charts-core, ag-charts-locale, ag-charts-community, and ag-charts-enterprise at the same version, which reduces stale declaration risk. It is maintained as a first-party workspace in the main AG Charts repository rather than as a separate volunteer-maintained typings project.

Ecosystem4/5The package recorded 3,184,738 weekly downloads and is an exact dependency of ag-charts-community 14.1.0, so it reaches every current Community installation as well as Enterprise and framework integrations. Its generic data and context parameters are useful to wrapper authors. Most of that usage is transitive, though, and the types are intentionally specific to the AG Charts configuration model rather than a reusable charting standard.

Use it if

You publish a TypeScript wrapper or configuration builder that must accept AG Charts options without depending on a renderer package
You need precise generic types for chart data, callback context, events, series, themes, or chart instances in shared code
You are extending an AG Grid integration and need the same chart contracts used by both Community and Enterprise packages
You deliberately isolate type-only imports from a matching version of the AG Charts runtime

Skip it if

You expect to render a chart: this package does not export the AgCharts implementation, and its JavaScript entry point only contains two tooltip enums plus internal verification placeholders
Your app already installs ag-charts-community 14.1.0: that runtime declares an exact dependency on ag-charts-types 14.1.0, so a second direct declaration is usually unnecessary
You cannot keep versions aligned: ag-charts-community pins ag-charts-core, ag-charts-locale, and ag-charts-types to the same exact version rather than a compatible range
You think an exported type makes a feature free to use: declarations include Sankey, maps, financial charts, zoom, and other features the README assigns to the commercially licensed Enterprise runtime
You want a slow-moving public type contract: major versions 10, 11, 12, 13, and 14 were published between July 2024 and June 2026, and version 14 represents axes as a keyed dictionary rather than the array shape found in older examples

Setup reality

For normal application code, install ag-charts-community and import its public API; it already pulls in the exact ag-charts-types version it was built against. Add ag-charts-types directly only when a package boundary needs to expose AG Charts contracts without importing the renderer. If you do that, pin both packages to the same release, for example 14.1.0. There are no peer dependencies, native builds, credentials, CSS files, or code-generation steps. Both CommonJS and ESM entry points exist, and TypeScript declarations are exposed at the package root; a separate ag-charts-types/scene export exists for low-level scene contracts. Prefer import type for interfaces so the tiny JavaScript entry point does not enter your bundle. Two tooltip enums are real runtime values and require a normal import. The biggest first-run surprise is that no chart appears because this package has no AgCharts.create implementation. A second is type/runtime skew: a newer declaration can accept an option an older renderer does not understand. Version 14 also models cartesian axes as an object keyed by x, y, or your own axis IDs, so snippets using axes: [...] from older releases fail type checking. The declaration tree covers both Community and Enterprise capabilities, but only ag-charts-enterprise supplies commercially licensed series and interactions. The package README is generated from the main product README and describes a charting library, so use the declarations and the matching version of the official chart documentation when the README wording conflicts with the actual package contents.

Patterns

Pin the types to the renderer versioninstall-matching-runtime

npm install ag-charts-community@14.1.0 ag-charts-types@14.1.0

ag-charts-community already depends on ag-charts-types at the same exact version. Add the direct dependency only when your own package imports or re-exports these contracts.

Type a complete chart options objecttype-basic-chart

import { AgCharts } from 'ag-charts-community';
import type { AgChartOptions } from 'ag-charts-types';

type Sale = { month: string; revenue: number };

const options: AgChartOptions<Sale> = {
  container: document.querySelector('#chart'),
  data: [
    { month: 'Jan', revenue: 42 },
    { month: 'Feb', revenue: 57 },
  ],
  series: [{ type: 'line', xKey: 'month', yKey: 'revenue' }],
};

AgCharts.create(options);

AgChartOptions supplies compile-time checking only. AgCharts.create comes from ag-charts-community, not from ag-charts-types.

Check a series without widening its typepreserve-series-literals

import type { AgLineSeriesOptions } from 'ag-charts-types';

type Sale = { month: string; revenue: number };

const revenueSeries = {
  type: 'line',
  xKey: 'month',
  yKey: 'revenue',
  yName: 'Revenue',
  marker: { enabled: true },
} satisfies AgLineSeriesOptions<Sale>;

satisfies keeps the type discriminator as the literal line and checks xKey and yKey against the Sale keys.

Use the version 14 keyed axis shapeconfigure-v14-axes

import type { AgCartesianChartOptions } from 'ag-charts-types';

type Sale = { month: string; revenue: number };

const axes: AgCartesianChartOptions<Sale>['axes'] = {
  x: { type: 'category', position: 'bottom' },
  y: {
    type: 'number',
    position: 'left',
    label: { format: '$,.0f' },
  },
};

Version 14 uses a dictionary keyed by x, y, or custom axis IDs. An axes array copied from an older AG Charts example is the wrong shape.

Build a typed stacked bar seriestype-bar-series

import type { AgBarSeriesOptions } from 'ag-charts-types';

type Quarter = { quarter: string; product: number; services: number };

const product: AgBarSeriesOptions<Quarter> = {
  type: 'bar',
  xKey: 'quarter',
  yKey: 'product',
  yName: 'Product',
  stacked: true,
  stackGroup: 'revenue',
};

grouped and stacked express different layouts. normalizedTo has no effect when grouped is true, as the 14.1.0 declaration documents.

Type a line tooltip renderertype-tooltip-renderer

import type {
  AgLineSeriesOptions,
  AgLineSeriesTooltipRendererParams,
} from 'ag-charts-types';

type Sale = { month: string; revenue: number };

const renderer = ({ datum }: AgLineSeriesTooltipRendererParams<Sale>) => ({
  title: datum.month,
  data: [{ label: 'Revenue', value: `$${datum.revenue}` }],
});

const series: AgLineSeriesOptions<Sale> = {
  type: 'line', xKey: 'month', yKey: 'revenue',
  tooltip: { renderer },
};

Version 14 accepts structured tooltip content with title and data rows. Returning a DOM element is not part of this series renderer result.

Give a node event its datum typetype-chart-listener

import type { AgNodeClickEvent } from 'ag-charts-types';

type Sale = { id: string; month: string; revenue: number };

function onSaleClick(
  event: AgNodeClickEvent<'seriesNodeClick', Sale>,
) {
  console.log(event.datum.id, event.seriesId, event.itemId);
}

Set dataIdKey in chart options when itemId must remain stable across updates; otherwise the renderer may generate identifiers.

Carry application context into callbackstype-callback-context

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

type Sale = { month: string; revenue: number };
type AppContext = { currency: string };

const options: AgChartOptions<Sale, AppContext> = {
  data: [{ month: 'Jan', revenue: 42 }],
  context: { currency: 'USD' },
  series: [{
    type: 'line', xKey: 'month', yKey: 'revenue',
    tooltip: {
      renderer: ({ datum, context }) =>
        `${context?.currency} ${datum.revenue}`,
    },
  }],
};

The second generic controls context in callbacks. Context remains optional in callback parameters, so handle undefined even when the options object supplies it.

Create a checked theme objecttype-custom-theme

import type { AgChartTheme } from 'ag-charts-types';

const theme: AgChartTheme = {
  baseTheme: 'ag-default-dark',
  palette: {
    fills: ['#5b8ff9', '#61d9a5', '#f6bd16'],
    strokes: ['#ffffff'],
  },
};

A custom palette replaces the base palette rather than extending individual entries. Supply enough fills for the number of series you display.

Describe code that owns a chart instancetype-chart-instance

import type {
  AgChartOptions,
  AgTypedChartInstance,
} from 'ag-charts-types';

type Sale = { month: string; revenue: number };
type SaleOptions = AgChartOptions<Sale>;
type SaleChart = AgTypedChartInstance<Sale, unknown, SaleOptions>;

async function replaceChart(chart: SaleChart, options: SaleOptions) {
  await chart.update(options);
  await chart.waitForUpdate();
}

update expects a complete valid options object. Use the instance's updateDelta method for partial changes, and batch rapid changes to avoid repeated redraws.

Import the two runtime tooltip enumsuse-runtime-enums

import {
  AgTooltipAnchorToType,
  AgTooltipPlacementType,
} from 'ag-charts-types';
import type { AgChartTooltipOptions } from 'ag-charts-types';

const tooltip: AgChartTooltipOptions = {
  position: {
    anchorTo: AgTooltipAnchorToType.NODE,
    placement: [
      AgTooltipPlacementType.TOP,
      AgTooltipPlacementType.BOTTOM,
    ],
  },
};

These enums are JavaScript values, so do not import them with import type. Nearly every other export from the root is a compile-time declaration.

Type an Enterprise-only Sankey seriesrecognize-enterprise-types

import type { AgSankeySeriesOptions } from 'ag-charts-types';

type Link = { from: string; to: string; amount: number };

const flow: AgSankeySeriesOptions<Link> = {
  type: 'sankey',
  fromKey: 'from',
  toKey: 'to',
  sizeKey: 'amount',
};

This compiling does not make Sankey available in ag-charts-community. The README lists Sankey under ag-charts-enterprise, whose npm package uses a commercial license.

Alternatives

Package	Registry	Pick it when
ag-charts-community	npm	You actually need to render AG Charts and want the MIT-licensed core series with matching types included transitively
chart.js	npm	You want a popular canvas chart runtime whose public package includes its own TypeScript declarations
echarts	npm	You need a broad chart catalog and one package containing both the renderer and TypeScript types
recharts	npm	You prefer React components and props over a framework-neutral options object