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 1.5.0; use its
release-source documentation.
Releases before 1.0 follow the Alpha policy and may
break APIs between minor releases. The stable compatibility contract
applies starting with 1.0. Check the policy for your installed version before upgrading.
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.
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',
}),
],
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.
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.
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
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
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
… 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:
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.
License
MIT © Tanner Linsley. See
ACKNOWLEDGEMENTS.md for project lineage.