Become a Sponsor!

TanStack Charts

A TypeScript visualization grammar for responsive, accessible, server-rendered application charts.

Important

This README follows unreleased main. The latest published release is TanStack Charts 0.12.0; use its release-source documentation. It is pre-alpha and not ready for production use.

Most chart libraries are easy until the chart stops being standard. TanStack Charts gives you one typed grammar that can grow from a familiar line or bar chart into a product-specific visualization without replacing your data model or dropping down to a separate API.

Keep your data as it is. Marks consume arrays, objects, tuples, and iterables directly. Different layers can use different datum types.
Compose the primitives that fit. Use compact scales and row transforms for common work, and pass native D3 callables directly when their fuller semantics are useful.
Build from common to custom. Layer built-in marks or implement a custom mark against the same public scene protocol.
Get the application runtime too. Responsive layout, automatic guide margins, themes, interaction, animation, accessibility, SVG SSR, opt-in Canvas painting, hydration, and export are part of the system.
Pay for what you import. Marks, transforms, layouts, renderers, and chart-owned interactions have independent subpaths. Optional D3-backed capabilities and direct D3 imports remain granular and tree-shakeable.

Read the docs →

Quick look

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 revenue = [
  { month: 'Jan', value: 42 },
  { month: 'Feb', value: 58 },
  { month: 'Mar', value: 76 },
  { month: 'Apr', value: 64 },
]

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

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

Marks consume the original rows, channels describe their visual encodings, and compact scale factories infer domains from those channels. A configured scale instance keeps its authored domain. TanStack assigns responsive pixel ranges, compiles a renderer-neutral keyed scene, and hands that scene to the selected host. Replace only the scale that needs fuller semantics with its direct d3-scale counterpart.

Definitions are framework-independent. The same revenueChart can render through React, Preact, Vue, Solid, Svelte, Angular, Lit, Alpine, Octane, the vanilla DOM host, static SVG, or the optional Canvas renderer.

When SVG element count becomes the bottleneck, switch the adapter import and keep the definition and host callbacks:

import { Chart } from '@tanstack/charts/react/canvas'

Canvas stays outside the default bundles. React and Octane also expose a renderer-neutral /core entry when an application owns the surface. Canvas removes per-mark DOM cost, not scene memory or dense nearest-point work, so large interactive charts should still use a measured spatial index or a bounded representation.

Package

Install @tanstack/charts once. Its exact subpaths expose compact scales, framework adapters, renderers, and optional capabilities without pulling unrelated code into application bundles:

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

The source remains split into focused workspace packages for development and verification. Those internal boundaries are assembled into the published @tanstack/charts package. Existing package names remain published for compatibility, but new applications do not need them.

The earlier host experiment remains under @plot-poc/* for migration evidence and benchmark comparison. The private @tanstack/charts-d3 package preserves a superseded backend experiment.

Core model

TanStack Charts deliberately splits ownership:

Layer	Owns
TanStack compact scales	Common numeric linear, categorical band and point, and categorical ordinal mappings
Granular D3 modules	Temporal, nonlinear, piecewise, spatial, layout, and other specialized algorithms
TanStack Charts	Marks, channels, responsive ranges, guide layout, scene compilation, rendering, and lifecycle

This boundary keeps specialized algorithms visible and replaceable while giving applications a consistent runtime. There is no global registry, library-owned dataframe, or chart-type configuration model.

Lineage

TanStack Charts is an independent implementation. Its conceptual lineage and the projects and people whose work informed it are credited in ACKNOWLEDGEMENTS.md.

Built almost entirely with AI

I designed TanStack Charts and directed its architecture, API, tradeoffs, and final decisions. Almost all of the implementation was produced with AI coding agents under my direct supervision, then reviewed and accepted into the project.

For live application state, memoize the complete defineChart(...) result with the framework's native memoization primitive. Definition identity is the application update boundary, while responsive definition callbacks still receive the current chart size and theme. The definition drives host prop and callback inference, so normal authoring does not require adapter generics, mark-array annotations, or casts. See Chart Definitions for the complete pattern.

Documentation

Start here	Use it for
`docs/overview.md`	Product model, responsibilities, and defaults
`docs/comparison.md`	Pinned capability and bundle comparison
`docs/quick-start.md`	First complete framework-agnostic chart
`docs/concepts/grammar-of-graphics.md`	Marks, channels, scales, and composition
`docs/concepts/scales-and-d3.md`	Compact scale path and D3 upgrade boundary
`docs/examples/index.md`	Curated chart-family and interaction examples
`docs/guides/ai-authoring.md`	Deterministic authoring and validation for coding agents
`docs/reference/index.md`	Complete public API map
`llms.txt`	Generated documentation routing index

Architecture decisions and open production gates live in PLAN.md. Evidence from real authoring and migration work is tracked in API-FRICTION.md.

Get Involved

We welcome issues and pull requests.
Chat with the community on Discord.
Follow the project through the roadmap and conformance catalog.

Partners

We're looking for TanStack Charts Partners to join our mission! Partner with us to push the boundaries of TanStack Charts and build amazing things together.

LET'S CHAT

Explore the TanStack Ecosystem

TanStack Config – Tooling for JS/TS packages
TanStack DB – Reactive sync client store
TanStack DevTools – Unified devtools panel
TanStack Form – Type-safe form state
TanStack Pacer – Debouncing, throttling, and batching
TanStack Query – Async state and caching
TanStack Ranger – Range and slider primitives
TanStack Router – Type-safe routing, caching, and URL state
TanStack Start – Full-stack SSR and streaming
TanStack Store – Reactive data store
TanStack Table – Headless datagrids
TanStack Virtual – Virtualized rendering

… and more at TanStack.com »

Development

The workspace requires Node.js 22 or newer and pnpm 11. Use the version in .nvmrc. See Contributing for the Nx CI graph, changeset requirements, and automated OIDC release flow.

pnpm install
pnpm run validate
pnpm test
pnpm typecheck
pnpm build
pnpm package:check

Run a local example:

pnpm dev:charts-react
pnpm dev:charts-octane
pnpm dev:sandbox
pnpm dev:interaction-geometry
pnpm dev:conformance

The sandbox opens its existing integrated data dashboard by default. The interaction-geometry command opens a before-and-after lab for exercising scene-owned interaction geometry, paint order, transforms, clipping, and natural focus fallback across chart families.

The repository includes three complementary benchmark suites:

benchmarks/bundle-size locks ordinary consumer bundles and isolates optional feature costs.
benchmarks/comparison compares equivalent line, bar, area, and scatter consumers across chart libraries, including a large-data and update stress matrix.
benchmarks/conformance exercises a broad, typed catalog against multiple reference renderers.

pnpm bundle:check
pnpm performance
pnpm performance:pointer
pnpm benchmark:check
pnpm benchmark:stress:quick
pnpm conformance:quick

These measurements are development evidence, not release claims. See each suite's README for its protocol, output, and limitations.

Pull requests gate formatting, types, tests, packed exports and declarations, locked bundles, comparison bundles, catalog metadata, browser comparison, and the quick five-library stress matrix. Conformance is monitored separately with a rotating nightly shard, a complete weekly matrix, manual runs, and an opt-in full-conformance pull-request label.

License

MIT © Tanner Linsley. See ACKNOWLEDGEMENTS.md for project lineage.