tanstack-charts

TanStack Charts

Use this skill when work touches TanStack Charts, especially mark composition, transforms, the scales registry, compact vs D3 scales, React Chart, SSR, tooltips/focus, Canvas, optional motion(), React Native, spatial/hierarchy/network entries, or migrations.

Treat the library as Alpha (0.18.0 at skill refresh; official Alpha since 0.16.0). Alpha is for evaluation and early integration: minor releases may break APIs, so pin an exact version. Verify current docs and the npm latest version before relying on edge APIs. Prefer GitHub tag v0.18.0 docs over stale search, pre-Alpha snippets with root x / y, or archived react-charts.

Workflow

1. Confirm the stack is the new TanStack Charts on the unified package:
   • Correct: bun add @tanstack/charts plus framework peers. Import Chart from @tanstack/charts/react, scales from @tanstack/charts/scales/linear (and /band, /point, /ordinal).
   • Compatibility only: @tanstack/react-charts, @tanstack/charts-scales, and other @tanstack/*-charts adapter packages still exist for existing apps. Do not add them to new code.
   • Wrong: unscoped react-charts, or options / primaryAxis / secondaryAxes / UserSerie.
2. Refresh versions and URLs from source-map.md.
3. Installation, defineChart, the scales registry, named scales/multiple axes, axes and guide styles, legends, tooltip extensions: setup-core.md.
4. Marks, bar radii, decorative, per-mark Canvas, polar/geo, composites: marks-composition.md.
5. Eager transforms vs mark layout: transforms-layouts.md.
6. Adapters, sizing, focus, crosshair, brush/zoom/cursor/selection, motion, SSR: frameworks-interaction.md.
7. Alpha stability, breaking migrations (root scales to scales), testing, large data, Canvas, custom marks, AI checks: production-patterns.md.

Implementation Judgment

• A chart is a composition of marks, not a chart-type component. Prefer the smallest mark set that answers the question.
• Keep rows in their natural shape. Do not invent a library-owned series wrapper.
• Install one package: @tanstack/charts. Compact scales: exact @tanstack/charts/scales/* (no /scales barrel). Import and declare every d3-* the application source uses. Pass factories for inferred domains, or configured instances for fixed domains. Never assign pixel ranges to positional scales the chart owns.
• Put positional scales in the scales registry: scales: { x, y } is required on every definition (null for an unused dimension), and polar views use polar({ scales: { angle, radius } }). Root x / y / angle / radius were removed in 0.16.0. Add named scales (channel, side) plus mark xScale / yScale only for a genuine second axis.
• Axis presentation lives under axis / axis.ticks / axis.tickLabels. axis: false hides a guide and keeps the scale. Set the scales entry to null only when no mark uses that dimension.
• Memoize the complete defineChart(...) against every captured value. Definition identity is the update boundary. Responsive { chart: ({ width }) => …, svgAnimation, tooltip, … } retains outer options.
• Default SVG animation option is svgAnimation, not animate. motion() ignores svgAnimation and reads definition-level motion.
• Bars/areas with a single length channel stack implicitly. Use layout: group() for side-by-side bars; layout: stack({ order, offset }) only when order/offset must be explicit; y1/y2 or x1/x2 opts out.
• Native tooltips: tooltip from @tanstack/charts/tooltip. Escape clipping with portal from @tanstack/charts/tooltip/portal. React renderTooltipBody requires @tanstack/charts/react/tooltip. Grouped rows default to visual mark order.
• Channel and transform accessors use (datum, { index, data }), not (datum, index, data).
• Rolling transforms: rollingWindow, not window. Reducer helper: delta, not difference.
• Supply ariaLabel on every mounted chart. Use focus: false to omit generated focus geometry; focusRing: false when authored focus marks replace the ring; focusDisabled when an app gesture owns the surface. Radial grouped focus: focusGroupAngle from @tanstack/charts/polar.
• Default to SVG. For paint-heavy layers, attach renderer: canvasChartRenderer to those marks instead of switching the whole chart. Import polar, geo, Canvas, export, motion, spatial, hierarchy, network, brush/zoom only through exact subpaths.
• Prefer built-in marks (boxY, waffleY, violinY, composites) before createMark. Wrap a sibling layer with decorative(...) when only one layer should own hit-testing.

Verification

Prefer the repo's existing checks. For meaningful Charts work, include the relevant subset:

• Package check: @tanstack/charts pinned to an exact 0.18.x (or the project's pin). New code imports adapters/scales from that package, not @tanstack/react-charts / @tanstack/charts-scales. Definitions use scales.x / scales.y.
• Typecheck for channels, scales, axis options, tooltip host brands, motion, ChartPoint callbacks—no unexpected casts.
• createChartScene / renderChartSvg for domains, geometry, keys, a11y markup.
• Interaction tests: focus, keyboard, tooltip, selection, brush/zoom, resize, empty data, destroy.
• Light/dark smoke when theme tokens or tooltip surface CSS change.
• SSR/hydration smoke for initialWidth, formatters, Canvas shells, idPrefix.
• Bundle measurement when adding polar, geo, Canvas, export, motion, spatial, hierarchy, network, or extra D3 modules.