TanStack Charts

https://tanstack.com/charts/latest/docs
Admin
TanStack Charts is a small, framework-agnostic chart grammar for TypeScript and JavaScript that...
Tokens:300,579
Snippets:2,138
Trust Score:9.4
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install Solid adapter with pnpm

Source: https://tanstack.com/charts/latest/docs/framework/solid/adapter.md

Install the @tanstack/charts package and solid-js as dependencies.

```sh
pnpm add @tanstack/charts solid-js
```

--------------------------------

### Install Alpine adapter

Source: https://tanstack.com/charts/latest/docs/framework/alpine/adapter.md

Install the required packages using pnpm.

```sh
pnpm add @tanstack/charts alpinejs
```

--------------------------------

### Install @tanstack/charts and vue

Source: https://tanstack.com/charts/latest/docs/framework/vue/adapter.md

Install the Vue adapter and the core charts package using pnpm.

```sh
pnpm add @tanstack/charts vue
```

--------------------------------

### Install TanStack Charts and Preact

Source: https://tanstack.com/charts/latest/docs/framework/preact/adapter.md

Command to install the required packages: `@tanstack/charts` and `preact`.

```sh
pnpm add @tanstack/charts preact
```

--------------------------------

### Install TanStack Charts and React peers

Source: https://tanstack.com/charts/latest/docs/framework/react/quick-start.md

Install the required packages using pnpm. The first command installs the main library and React dependencies, while the second installs TypeScript types for React.

```sh
pnpm add @tanstack/charts react react-dom
pnpm add -D @types/react @types/react-dom
```

--------------------------------

### Install @tanstack/charts and lit

Source: https://tanstack.com/charts/latest/docs/framework/lit/adapter.md

Install the @tanstack/charts package and the lit peer dependency for the Lit adapter.

```sh
pnpm add @tanstack/charts lit
```

--------------------------------

### Install @tanstack/charts and svelte

Source: https://tanstack.com/charts/latest/docs/framework/svelte/adapter.md

Install the @tanstack/charts package and the Svelte peer dependency.

```sh
pnpm add @tanstack/charts svelte
```

--------------------------------

### Usage examples for tickX and tickY

Source: https://tanstack.com/charts/latest/docs/reference/marks/rules-links-arrows-vectors-and-ticks.md

Examples demonstrating how to invoke tickX and tickY with various data sources and configuration options.

```ts
tickX(rows, { x: 'category', y: 'value', z: 'series' })
tickY(rows, { x: 'value', y: 'category', length: 16 })
tickY(summaries, { x: 'category', y: 'median', span: 0.36 })
```

--------------------------------

### Mounting with a new definition

Source: https://tanstack.com/charts/latest/docs/reference/dom-host.md

Example of initializing a host with a specific chart definition.

```ts
const host = mountChart(container, {
  definition: createDefinition(rows, 'revenue'),
  ariaLabel: 'Revenue by month',
})
```

--------------------------------

### Configure categorical bands and multiple crosshairs

Source: https://tanstack.com/charts/latest/docs/reference/focus-and-interaction.md

This example shows how to use a categorical band for the x-axis and a separate crosshair mark for the y-axis, demonstrating how to layer guides relative to other marks.

```ts
marks: [
  crosshair({
    x: {
      band: {
        inset: 0,
        radius: 3,
        fill: '#64748b',
        fillOpacity: 0.16,
      },
      label: true,
    },
    y: false,
  }),
  barY(rows, {
    x: 'period',
    y: 'value',
    color: 'series',
    inset: 4,
  }),
  crosshair({
    x: false,
    y: { strokeDasharray: '4 4', label: true },
  }),
]
```

--------------------------------

### Install Angular adapter packages

Source: https://tanstack.com/charts/latest/docs/framework/angular/adapter.md

Install the required packages for using TanStack Charts with Angular.

```sh
pnpm add @tanstack/charts @angular/common @angular/core @angular/platform-browser
```

--------------------------------

### Create crosshair guides for focus

Source: https://tanstack.com/charts/latest/docs/examples/interactive-charts.md

Adds two crosshair guides: one horizontal band guide below bars with x label, and one vertical dotted guide above bars with y label. The guides follow pointer and keyboard focus, are not hit-tested, and render through SVG, Canvas, and motion. The first guide uses categorical bandwidth to paint below the bars; the second paints above.

```typescript
marks: [
  crosshair({
    x: {
      band: {
        inset: 0,
        radius: 3,
        fill: '#64748b',
        fillOpacity: 0.16,
      },
      label: true,
    },
    y: false,
  }),
  barY(rows, { x: 'period', y: 'value', color: 'series', inset: 4 }),
  crosshair({
    x: false,
    y: { strokeDasharray: '4 4', label: true },
  }),
]
```

--------------------------------

### Install TanStack Charts and Octane with pnpm

Source: https://tanstack.com/charts/latest/docs/framework/octane/quick-start.md

Run this command to install the @tanstack/charts package and its Octane peer dependency.

```sh
pnpm add @tanstack/charts octane
```

--------------------------------

### link usage example

Source: https://tanstack.com/charts/latest/docs/reference/marks/rules-links-arrows-vectors-and-ticks.md

Example of using the `link` mark with required endpoint channels and optional styling options like strokeWidth and lineCap.

```ts
link(edges, {
  x1: 'sourceX',
  y1: 'sourceY',
  x2: 'targetX',
  y2: 'targetY',
  z: 'kind',
  strokeWidth: (edge) => edge.weight,
  lineCap: 'butt',
})
```

--------------------------------

### Install TanStack Charts

Source: https://tanstack.com/charts/latest/docs/concepts/scales-and-d3.md

Install the core package to access compact scales for ordinary numeric and categorical charts.

```sh
pnpm add @tanstack/charts
```

--------------------------------

### Install TanStack Charts for bare React Native 0.86

Source: https://tanstack.com/charts/latest/docs/installation.md

Use these commands for a bare React Native 0.86 application. After adding, run `bundle exec pod install` from the `ios/` directory.

```sh
pnpm add @tanstack/charts react react-native react-native-svg@^15.15.4
```

--------------------------------

### Verify TanStack Charts installation with createChartScene

Source: https://tanstack.com/charts/latest/docs/installation.md

Verifies the installation by creating a small scene without mounting it. Uses createChartScene with explicit width and height, then logs the scene chart and point count. Both positional scales are required; a missing scale is an authoring error rather than a hidden fallback.

```ts
import { scaleLinear } from '@tanstack/charts/scales/linear'
import { createChartScene, defineChart, lineY } from '@tanstack/charts'

const chart = defineChart({
  marks: [lineY([2, 5, 3])],
  scales: {
    x: { scale: scaleLinear },
    y: { scale: scaleLinear },
  },
})

const scene = createChartScene(chart, { width: 640, height: 320 })

console.log(scene.chart, scene.points.length)
```

--------------------------------

### Mounting a chart with responsive sizing options

Source: https://tanstack.com/charts/latest/docs/reference/dom-host.md

Example of initializing a chart with an aspect ratio and initial width to control responsive behavior.

```ts
mountChart(container, {
  definition,
  aspectRatio: 16 / 9,
  initialWidth: 720,
  ariaLabel: 'Traffic over time',
})
```

--------------------------------

### Define a basic crosshair guide

Source: https://tanstack.com/charts/latest/docs/reference/focus-and-interaction.md

This example demonstrates how to add a crosshair mark to a chart definition, configuring vertical and horizontal rules with specific dash patterns.

```ts
import { crosshair, defineChart, lineY } from '@tanstack/charts'

const definition = defineChart({
  marks: [
    lineY(rows, { x: 'date', y: 'value', color: 'series' }),
    crosshair({
      x: { label: true },
      y: false,
      strokeDasharray: '4 4',
    }),
  ],
  scales: {
    x: { scale: scaleUtc },
    y: { scale: scaleLinear },
  },

  focus: 'group-x',
  maxFocusDistance: Number.POSITIVE_INFINITY,
})
```

--------------------------------

### Define a chart with TanStack Charts in TypeScript

Source: https://tanstack.com/charts/latest/docs/installation.md

Shows the minimal TypeScript setup for defining a chart with TanStack Charts. Imports the linear scale and chart helpers, then creates a chart with a line mark and two positional scales. This example is intended for normal chart authoring and should not require adapter generics or casts.

```ts
import { scaleLinear } from '@tanstack/charts/scales/linear'
import { defineChart, lineY } from '@tanstack/charts'

const values = [4, 9, 7]

const chart = defineChart({
  marks: [lineY(values)],
  scales: {
    x: { scale: scaleLinear },
    y: { scale: scaleLinear },
  },
})
```

--------------------------------

### Create and sample a chart spring

Source: https://tanstack.com/charts/latest/docs/reference/motion.md

Demonstrates how to initialize a spring with specific physics parameters and sample its value at a given time.

```ts
import { createChartSpring } from '@tanstack/charts/spring'

const spring = createChartSpring({ stiffness: 170, damping: 18, mass: 1 })
const sample = spring.sample(16, { from: 0, to: 100, velocity: 0 })
```

--------------------------------

### Install other granular D3 capabilities

Source: https://tanstack.com/charts/latest/docs/installation.md

Install only what the application imports. Do not install the `d3` umbrella package.

```sh
# Examples: install only what the application imports
pnpm add d3-geo d3-quadtree d3-delaunay d3-selection d3-zoom d3-brush d3-time d3-scale-chromatic
pnpm add -D @types/d3-geo @types/d3-quadtree @types/d3-delaunay @types/d3-selection @types/d3-zoom @types/d3-brush @types/d3-time @types/d3-scale-chromatic
```

--------------------------------

### Create a density chart with responsive thresholds

Source: https://tanstack.com/charts/latest/docs/guides/large-data.md

This example demonstrates how to summarize data and define a chart that adjusts its binning thresholds based on the available width.

```ts
function summarizeDensity(rows: Input['rows']) {
  return summarizeSource(rows)
}

function createDensityChart(rows: Input['rows']) {
  const summary = summarizeDensity(rows)

  return defineChart(({ width }) => {
    const thresholds = width < 480 ? 12 : width < 900 ? 24 : 40
    const bins = buildSemanticBins(summary, { thresholds })
    return densitySpec(bins)
  })
}
```

--------------------------------

### Complete bubble-scatter example

Source: https://tanstack.com/charts/latest/docs/concepts/data-and-channels.md

A complete example demonstrating a bubble-scatter chart using data filtering, custom scales, and mark configuration. The example consists of the chart definition and the underlying data source.

```ts
import { scaleSqrt } from 'd3-scale'
import { colorLegend, defineChart, dot } from '@tanstack/charts'
import { scaleLinear } from '@tanstack/charts/scales/linear'
import { scaleOrdinal } from '@tanstack/charts/scales/ordinal'
import { penguins, type PenguinsRow } from './data'

type CompletePenguin = PenguinsRow & {
  culmen_length_mm: number
  culmen_depth_mm: number
  body_mass_g: number
}

const rows = penguins.filter(
  (row): row is CompletePenguin =>
    row.culmen_length_mm !== null &&
    row.culmen_depth_mm !== null &&
    row.body_mass_g !== null,
)
const species = ['Adelie', 'Chinstrap', 'Gentoo']

export default defineChart({
  marks: [
    dot(rows, {
      x: 'culmen_length_mm',
      y: 'culmen_depth_mm',
      color: 'species',
      r: 'body_mass_g',
      rScale: {
        scale: () => scaleSqrt().range([3, 11]),
      },
      fillOpacity: 0.78,
      stroke: 'currentColor',
      strokeOpacity: 0.28,
      strokeWidth: 0.75,
    }),
  ],
  scales: {
    x: {
      scale: scaleLinear,
      grid: true,
      axis: { label: 'Bill length (mm)' },
    },
    y: {
      scale: scaleLinear,
      grid: true,
      axis: { label: 'Bill depth (mm)' },
    },
  },

  color: {
    scale: scaleOrdinal(species, ['#2563eb', '#f97316', '#10b981']),
    legend: colorLegend({ label: 'Species' }),
  },
})
```

```ts
export interface PenguinsRow {
  species: string
  culmen_length_mm: number | null
  culmen_depth_mm: number | null
  body_mass_g: number | null
}

export const penguins: readonly PenguinsRow[] = [
  {
    species: 'Adelie',
    culmen_length_mm: 39.1,
    culmen_depth_mm: 18.7,
    body_mass_g: 3750,
  },
  {
    species: 'Adelie',
    culmen_length_mm: 40.3,
    culmen_depth_mm: 18,
    body_mass_g: 3250,
  },
  {
    species: 'Chinstrap',
    culmen_length_mm: 46.5,
    culmen_depth_mm: 17.9,
    body_mass_g: 3500,
  },
  {
    species: 'Chinstrap',
    culmen_length_mm: 50,
    culmen_depth_mm: 19.5,
    body_mass_g: 3900,
  },
  {
    species: 'Gentoo',
    culmen_length_mm: 46.1,
    culmen_depth_mm: 13.2,
    body_mass_g: 4500,
  },
  {
    species: 'Gentoo',
    culmen_length_mm: 50,
    culmen_depth_mm: 16.3,
    body_mass_g: 5700,
  },
  {
    species: 'Gentoo',
    culmen_length_mm: null,
    culmen_depth_mm: null,
    body_mass_g: null,
  },
]
```

--------------------------------

### Install TanStack Charts with framework peers

Source: https://tanstack.com/charts/latest/docs/installation.md

Add the selected framework peers when the application uses an adapter subpath. Each framework has its own command; choose the one that matches your framework.

```sh
# React
pnpm add @tanstack/charts react react-dom
```

```sh
# React Native
pnpm add @tanstack/charts react@^19.2.3 react-native@^0.86.0 react-native-svg@^15.15.4
```

```sh
# Preact
pnpm add @tanstack/charts preact
```

```sh
# Vue
pnpm add @tanstack/charts vue
```

```sh
# Solid
pnpm add @tanstack/charts solid-js
```

```sh
# Svelte
pnpm add @tanstack/charts svelte
```

```sh
# Angular
pnpm add @tanstack/charts @angular/core @angular/platform-browser
```

```sh
# Lit
pnpm add @tanstack/charts lit
```

```sh
# Alpine
pnpm add @tanstack/charts alpinejs
```

```sh
# Octane
pnpm add @tanstack/charts octane
```

--------------------------------

### Configuring ridgelineY with prepared profiles

Source: https://tanstack.com/charts/latest/docs/reference/marks/ridgeline.md

Demonstrates preparing data using binX and normalize before passing it to the ridgelineY mark within a chart definition.

```ts
const bins = binX(rows, {
  value: 'rating',
  by: 'season',
  thresholds: boundaries,
  outputs: { count: { reduce: 'count' } },
})
const profiles = normalize(bins, {
  value: 'count',
  by: 'season',
  basis: 'max',
  as: 'height',
})

defineChart({
  marks: [
    ridgelineY(profiles, {
      x: 'x',
      y: 'season',
      height: 'height',
      overlap: 0.78,
      color: 'season',
    }),
  ],
  scales: {
    x: { scale: scaleLinear().domain([4, 10]) },
    y: {
      scale: scalePoint<number>().domain(seasons).padding(0.78),
      reverse: true,
    },
  },
})
```

--------------------------------

### Importing tooltip entry point

Source: https://tanstack.com/charts/latest/docs/framework/react/adapter.md

Shows how to import the tooltip entry point to use renderTooltipBody.

```tsx
import {
  Chart,
  CanvasChart,
  RendererChart,
  type ChartTooltipBodyRenderContext,
} from '@tanstack/charts/react/tooltip'
```

--------------------------------

### Usage of lineX mark

Source: https://tanstack.com/charts/latest/docs/reference/marks/line-and-area.md

Example showing how to initialize a lineX mark with specific data channels and point rendering enabled.

```ts
const mark = lineX(rows, {
  x: 'value',
  y: 'category',
  z: 'series',
  points: true,
})
```

--------------------------------

### Prerender and mount lifecycle with createChartAdapter

Source: https://tanstack.com/charts/latest/docs/reference/adapter-controller.md

Shows the lifecycle of a chart adapter: create with options, prerender to get initial markup, then in the browser set the container's innerHTML, mount, update, and destroy. Server and browser controllers are separate instances; the browser's initial render and mount should reuse one browser controller.

```ts
const adapter = createChartAdapter(options)

const initialMarkup = adapter.prerender()

// In the browser lifecycle:
container.innerHTML = initialMarkup
adapter.mount(container)

adapter.update(nextOptions)
adapter.destroy()
```

--------------------------------

### Install TanStack Charts with pnpm

Source: https://tanstack.com/charts/latest/docs/installation.md

Install the core @tanstack/charts package in each application that authors chart definitions.

```sh
pnpm add @tanstack/charts
```

--------------------------------

### Basic mountChart usage

Source: https://tanstack.com/charts/latest/docs/reference/dom-host.md

Example of mounting a chart, updating its options, and destroying the host instance.

```ts
const options = {
  definition: defineChart(definition, { tooltip }),
  height: 320,
  ariaLabel: 'Weekly revenue',
}

const host = mountChart(container, options)

host.update({
  ...options,
  height: 400,
})

host.destroy()
```

--------------------------------

### Install d3-scale dependencies

Source: https://tanstack.com/charts/latest/docs/concepts/scales-and-d3.md

Commands to install the necessary D3 scale package and its corresponding TypeScript definitions.

```sh
pnpm add d3-scale
pnpm add -D @types/d3-scale
```

--------------------------------

### Run benchmark and conformance commands

Source: https://tanstack.com/charts/latest/docs/comparison.md

Run these commands to execute the size benchmark, check the bundle baseline, run the stress test, and verify conformance. The browser-backed commands require the pinned Playwright browser.

```sh
pnpm benchmark:size
pnpm benchmark:check
pnpm benchmark:stress:quick
pnpm conformance:quick
```

--------------------------------

### Import and usage of focusGuideX

Source: https://tanstack.com/charts/latest/docs/reference/marks/focus-guide.md

Imports focusGuideX from '@tanstack/charts/focus/guide' and configures it with options for id, x, y, z, key, rules, labels, and motion. The xRule is enabled by default for focusGuideX.

```ts
import { focusGuideX } from '@tanstack/charts/focus/guide'

focusGuideX(rows, {
  id: 'cursor',
  x: 'period',
  y: 'value',
  z: 'series',
  key: 'id',
  yRule: {},
  marker: {},
  xLabel: { format: (period) => period },
  yLabel: { format: (value) => String(value) },
  motion: {
    transition: { type: 'spring', stiffness: 240, damping: 22 },
  },
})
```

--------------------------------

### Configure axis guide options

Source: https://tanstack.com/charts/latest/docs/concepts/grammar-of-graphics.md

Axis guide options live next to their scale. The scale maps values; the guide makes that mapping legible. `ticks`, `format`, `label`, `grid`, `reverse`, `tickRotate`, and `labelOffset` are presentation controls for the axis and do not replace scale semantics.

```ts
const y = {
  scale: revenueScale,
  grid: true,
  axis: {
    label: 'Monthly revenue',
    ticks: {
      count: 5,
      format: (value: number) => `${Math.round(value / 1_000)}k`,
    },
  },
}
```

--------------------------------

### Implementing Voronoi Mark

Source: https://tanstack.com/charts/latest/docs/reference/marks/voronoi.md

Example showing how to import and use the voronoi mark alongside a dot mark to visualize data proximity.

```ts
import { dot } from '@tanstack/charts'
import { voronoi } from '@tanstack/charts/spatial/voronoi'

const marks = [
  voronoi(cars, {
    x: 'weight',
    y: 'economy',
    key: 'id',
    color: 'cylinders',
    fillOpacity: 0.14,
    stroke: '#fff',
    strokeWidth: 1,
  }),
  dot(cars, {
    x: 'weight',
    y: 'economy',
    key: 'id',
    color: 'cylinders',
  }),
]
```
Tokens:
Raw