### [Become a Sponsor!](https://github.com/sponsors/tannerlinsley/)
# 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.1.0`; use its
> [release-source documentation](https://github.com/TanStack/charts/tree/v1.1.0/docs).
> Releases before 1.0 follow the [Alpha policy](./docs/stability.md) and may
> break APIs between minor releases. The [stable compatibility contract](./docs/compatibility.md)
> 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.
### Read the docs →
## Quick look
```tsx
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 (
)
}
```
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:
```tsx
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:
```ts
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`](./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](./docs/concepts/chart-definitions.md) for the complete
pattern.
## Documentation
| Start here | Use it for |
| -------------------------------------------------------------------------------- | -------------------------------------------------------- |
| [`docs/overview.md`](./docs/overview.md) | Product model, responsibilities, and defaults |
| [`docs/comparison.md`](./docs/comparison.md) | Pinned capability and bundle comparison |
| [`docs/quick-start.md`](./docs/quick-start.md) | First complete framework-agnostic chart |
| [`docs/concepts/grammar-of-graphics.md`](./docs/concepts/grammar-of-graphics.md) | Marks, channels, scales, and composition |
| [`docs/concepts/scales-and-d3.md`](./docs/concepts/scales-and-d3.md) | Compact scale path and D3 upgrade boundary |
| [`docs/examples/index.md`](./docs/examples/index.md) | Curated chart-family and interaction examples |
| [`docs/guides/ai-authoring.md`](./docs/guides/ai-authoring.md) | Deterministic authoring and validation for coding agents |
| [`docs/reference/index.md`](./docs/reference/index.md) | Complete public API map |
| [`llms.txt`](./llms.txt) | Generated documentation routing index |
Architecture decisions and open production gates live in
[`PLAN.md`](./PLAN.md). Evidence from real authoring and migration work is
tracked in [`API-FRICTION.md`](./API-FRICTION.md).
## Get Involved
- We welcome issues and pull requests.
- Chat with the community on [Discord](https://discord.com/invite/WrRKjPJ).
- Follow the project through the [roadmap](./PLAN.md) and
[conformance catalog](./benchmarks/conformance).
## 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](./CONTRIBUTING.md) for the Nx CI graph, changeset
requirements, and automated OIDC release flow.
```sh
pnpm install
pnpm run validate
pnpm test
pnpm typecheck
pnpm build
pnpm package:check
```
Run a local example:
```sh
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`](./benchmarks/bundle-size) locks ordinary consumer
bundles and isolates optional feature costs.
- [`benchmarks/comparison`](./benchmarks/comparison) compares equivalent line,
bar, area, and scatter consumers across chart libraries, including a
[large-data and update stress matrix](./benchmarks/comparison/stress).
- [`benchmarks/conformance`](./benchmarks/conformance) exercises a broad,
typed catalog against multiple reference renderers.
```sh
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](./LICENSE) © Tanner Linsley. See
[`ACKNOWLEDGEMENTS.md`](./ACKNOWLEDGEMENTS.md) for project lineage.
