TanStack/charts

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

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.

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',
    }),
  ],
  scales: {
    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.

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.

TanStack Charts deliberately splits ownership:

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.

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

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.

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

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

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

• 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 »

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: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.

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