TanStack Charts: a TypeScript visualization grammar built on granular D3 primitives

The problem TanStack Charts targets: charts that stop being standard

The README opens with a blunt claim: most chart libraries are easy until the chart stops being standard. That is the gap this project aims at. A dashboard line chart is a solved problem in a dozen libraries. The moment a product needs a bespoke encoding, a custom mark, or a datum type the library never anticipated, teams usually either fork the library or drop to raw D3 and rebuild the surrounding runtime by hand. TanStack Charts tries to make that transition continuous rather than a rewrite.

The intended audience is application engineers already comfortable with TypeScript and D3 concepts, working in React, Preact, Vue, Solid, Svelte, Angular, Lit, Alpine, Octane or the vanilla DOM host. It is not aimed at analysts who want a drag-and-drop builder, and the README never suggests otherwise. Definitions are framework-independent, so the same chart object can render through any listed host.

How the grammar works: marks, channels, scales, and a compiled scene

The core loop is small. You write a chart definition with marks and scales. Marks consume your original rows directly, whether those are arrays, objects, tuples or iterables, and different layers may use different datum types. Channels describe the visual encoding of those rows. Compact scale factories infer domains from the channels, while a configured scale instance keeps its authored domain. TanStack then assigns responsive pixel ranges, compiles a renderer-neutral keyed scene, and hands that scene to the selected host.

The ownership split is stated explicitly in a table in the README. TanStack compact scales own common numeric linear, categorical band and point, and categorical ordinal mappings. Granular D3 modules own temporal, nonlinear, piecewise, spatial and layout algorithms. TanStack Charts owns marks, channels, responsive ranges, guide layout, scene compilation, rendering and lifecycle. That boundary is the interesting design decision: specialized algorithms stay visible and replaceable instead of being reimplemented behind a private wrapper. You can replace a single scale with its direct d3-scale counterpart when you need fuller semantics, without abandoning the rest of the definition.

Because the scene is renderer-neutral, the same definition can be painted as SVG, as static SVG for server rendering, or through the opt-in Canvas renderer. The README notes that Canvas removes per-mark DOM cost but not scene memory or dense nearest-point work, so large interactive charts should still use a measured spatial index or a bounded representation. That is an honest constraint rather than a marketing claim.

Installing @tanstack/charts and rendering a first bar chart

The package is published as @tanstack/charts, and the README says to install it once. Its exact subpaths expose compact scales, framework adapters, renderers and optional capabilities without pulling unrelated code into bundles. There is no separate install step documented for the React adapter; it is a subpath of the same package.

pnpm add @tanstack/charts

Imports come from three distinct subpaths in the README example: the main entry for marks and defineChart, the scale subpaths for scaleBand and scaleLinear, and the React adapter for the Chart component.

import { scaleLinear } from '@tanstack/charts/scales/linear'
import { Chart } from '@tanstack/charts/react'
import { Chart as CanvasChart } from '@tanstack/charts/react/canvas'

The README's quick-look example defines a chart over an array of month and value objects. barY takes the rows and names the x and y channels, the x scale is a band scale with padding, and the y scale is linear with nice, grid and an axis label. The tooltip import is passed as a chart-owned interaction.

import { barY, defineChart } from '@tanstack/charts'
import { scaleBand } from '@tanstack/charts/scales/band'
import { scaleLinear } from '@tanstack/charts/scales/linear'
import { tooltip } from '@tanstack/charts/tooltip'
import { Chart } from '@tanstack/charts/react'

const revenueChart = defineChart({
  marks: [barY(revenue, { x: 'month', y: 'value' })],
  scales: {
    x: { scale: () => scaleBand().padding(0.2) },
    y: { scale: scaleLinear, nice: true, grid: true, axis: { label: 'Revenue' } },
  },
  tooltip,
})

Rendering is a single component with an explicit height and an accessible label. The README passes height={320} and ariaLabel="Monthly revenue", which is a reasonable signal that accessibility is part of the runtime rather than an afterthought.

export function RevenueChart() {
  return (
    <Chart definition={revenueChart} height={320} ariaLabel="Monthly revenue" />
  )
}

Switching to Canvas is documented as an adapter import change: import Chart from @tanstack/charts/react/canvas and keep the definition and host callbacks. The README states Canvas stays outside default bundles.

Alpha status, breaking changes, and the version pinning rule

The README carries an explicit warning block. The published release line is Alpha, versions use regular 0.x numbering, and breaking changes may land between minor releases. The documented advice is to pin an exact version for production use and read the Alpha stability policy in docs/stability.md before upgrading. The last push to the repository was on 2026-09-15, and the most recent release listed is v0.18.0 from 2026-09-10, with v0.17.0 and v0.16.2 arriving the day before that. Three releases in roughly a week is a fast cadence, and it cuts both ways: fixes arrive quickly, and so do surface changes.

There is a second trap the README names directly. The README follows unreleased main, described as the official Alpha line, while the latest published release is 0.18.0. Anyone reading the README as documentation for the installed version is reading ahead of their own dependency. The README points to release-source documentation at the v0.18.0 tag for the published behaviour. That mismatch is worth internalising before filing an issue about an API that does not exist in your version.

Where TanStack Charts is the wrong tool

If you want a library that hands you a fixed catalogue of chart types with a stable API and no D3 vocabulary, this is not it. The README describes a grammar, and grammars require you to compose marks, channels and scales yourself. The quick-look example is a bar chart, but everything around it, from scale choice to guide configuration, is authored by the application.

Canvas is also not a blanket performance answer. The README is explicit that Canvas removes per-mark DOM cost but not scene memory or dense nearest-point work, and that large interactive charts should still use a measured spatial index or a bounded representation. If your bottleneck is nearest-point hit testing over tens of thousands of points, changing the adapter import will not fix it.

The repository also carries a private package, @tanstack/charts-d3, described as preserving a superseded backend experiment, and an earlier host experiment under @plot-poc/* kept for migration evidence and benchmark comparison. That is normal for an alpha, but it means the repository's internal package boundaries do not map cleanly onto the single published package, and older package names remain published for compatibility. A reader browsing packages/ should not assume those boundaries are the public API.

How this differs from a D3-only or component-library approach

The direct alternative for this audience is writing the visualization in D3 yourself. D3 gives you the algorithms and the SVG manipulation, but you own responsive ranges, guide margins, theming, interaction, animation, accessibility, SSR, hydration and export. The README lists exactly those as part of the system rather than as your problem. That is the actual difference in approach: TanStack Charts keeps D3's specialized algorithms reachable through granular modules and direct imports, while supplying the application runtime around them.

The other common alternative is a component chart library, which inverts the trade-off. You get a stable, documented component surface, and you accept that a non-standard encoding means either an escape hatch or a fork. TanStack Charts' answer is to make the escape hatch the same public protocol: the README says you can layer built-in marks or implement a custom mark against the same public scene protocol. Whether that protocol is pleasant to implement against is something the documentation, not this article, has to demonstrate.

Licence, maintenance signals, and what upgrading costs

The licence is MIT, stated in the README badge, the repository LICENSE file and the workspace package.json. MIT permits commercial use and modification, but this is a statement of the licence text, not legal advice; check the LICENSE file and your own obligations.

On maintenance, the evidence available is the last push on 2026-09-15 and the release cadence around v0.18.0. The repository is not archived. The upgrade cost is the concrete thing to weigh: the README warns that minor releases may contain breaking changes, so an upgrade is a code change, not a version bump. Pinning an exact version and reading docs/stability.md before each move is the documented path. The repository also ships a validate script, nx run charts-workspace:ci plus git diff --check, and a set of benchmark scripts, which tells you the project measures itself, though the README does not document rollback or a deprecation window.

Editorial conclusion

TanStack Charts suits teams building product-specific visualizations who want one typed grammar across SSR, hydration and an optional Canvas renderer, and who can pin an exact version and absorb breaking changes between minor releases. It is the wrong choice if you need a stable API today, a gallery of ready-made chart types, or a charting layer that hides D3 behind a fixed component set. Before adopting, read docs/stability.md, check the release-source documentation for v0.18.0 against the main branch README, and confirm which subpaths your bundler resolves.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. TanStack/charts on GitHub