@tanstack/charts
Version:
A chart grammar for TypeScript and JavaScript. Marks consume your data directly, channels describe visual encodings, and the engine compiles them into a renderer-neutral keyed scene. TanStack's compact scales cover common numeric and categorical mappings.
42 lines (31 loc) • 2.87 kB
Markdown
# Migrate From Chart.js
Chart.js combines dataset configuration, controllers, plugins, a Canvas renderer, and imperative instance updates. Separate those responsibilities before translating them.
## Ownership Map
| Chart.js concern | Inspect | TanStack destination |
| -------------------------- | ------------------------------------------ | ---------------------------------------------------------- |
| `data.labels` and datasets | row identity, implicit x, dataset grouping | explicit rows and channels per mark |
| dataset `type` | geometry and mixed-chart layering | mark family and declaration order |
| `parsing` | field mapping and coercion | typed row preparation and channel accessors |
| scale config | domain, stack, reverse, tick callback | factory/instance, mark layout, axis guide |
| plugin | lifecycle, drawing, events, external UI | mark, control, renderer/host extension, or application UI |
| imperative `update` | changed data/options and animation mode | new definition identity passed to host/adapter |
| Canvas output | raster performance and export | choose TanStack Canvas or SVG/static renderer deliberately |
## Sequence
1. Convert labels plus parallel dataset arrays into typed semantic rows.
2. Preserve dataset IDs as series and datum IDs as keys.
3. Classify each plugin: geometry, interaction, application UI, export, or lifecycle.
4. Recreate scale domains and mark layouts independently of Canvas pixels.
5. Rebuild the definition when accepted data/options change; do not mutate a retained chart spec.
6. Choose SVG or Canvas from actual mark count and interaction/export requirements.
## High-Risk Differences
- Parallel arrays hide row identity. Create rows before comparing updates or tooltips.
- Chart.js plugins can draw arbitrary Canvas pixels. A TanStack replacement must declare semantic scale values and renderer-neutral scene ownership unless it is deliberately renderer-specific.
- Dataset order may control stacking, legend, tooltip, and paint at once. Split those policies explicitly.
- Canvas screenshot parity does not prove keyboard accessibility or semantic focus points.
## Parity Cases
- Mixed chart layers paint in the same semantic order.
- Dataset filtering retains color and domain policy.
- Plugin annotations become stable marks rather than after-draw mutations.
- Imperative updates preserve keys and latest-wins behavior.
- Raster export, pixel ratio, and sustained pointer work meet the target budget.
Source: `docs/guides/migrating.md`; `docs/guides/custom-marks-and-renderers.md`