Quick Start

This walkthrough uses the framework-agnostic DOM host. The same chart definition passes unchanged to any supported framework adapter.

1. Add a chart container#

<div id="closing-price-chart"></div>

The host follows the container width when width is omitted.

2. Define the data and chart#

import { scaleLinear, scaleUtc } from 'd3-scale'
import { defineChart, lineY, mountChart } from '@tanstack/charts'

interface ClosingPrice {
  Date: Date
  Close: number
}

const closingPrices: readonly ClosingPrice[] = [
  { Date: new Date('2013-11-01T00:00:00Z'), Close: 74.29 },
  { Date: new Date('2013-12-02T00:00:00Z'), Close: 78.75 },
  { Date: new Date('2014-01-02T00:00:00Z'), Close: 79.02 },
  { Date: new Date('2014-02-03T00:00:00Z'), Close: 71.65 },
  { Date: new Date('2014-03-03T00:00:00Z'), Close: 75.39 },
  { Date: new Date('2014-04-01T00:00:00Z'), Close: 77.38 },
  { Date: new Date('2014-05-01T00:00:00Z'), Close: 84.5 },
]

const closingPriceChart = defineChart({
  marks: [
    lineY(closingPrices, {
      id: 'apple-close',
      x: 'Date',
      y: (row) => (row.Date.getUTCMonth() < 3 ? null : row.Close),
      stroke: '#2563eb',
    }),
  ],
  x: {
    scale: scaleUtc,
    nice: true,
    label: 'Date',
  },
  y: {
    scale: scaleLinear,
    nice: true,
    label: 'Close (USD)',
    grid: true,
  },
  tooltip: true,
})

Because this source imports d3-scale directly, add it and @types/d3-scale as direct dependencies. See Installation.

The accessor deliberately omits first-quarter observations, creating visible breaks instead of misleading segments. The original closing-price row flows through the mark and into interaction callbacks; no cast or manual chart generic is needed.

3. Mount it#

const container = document.querySelector<HTMLElement>('#closing-price-chart')

if (!container) {
  throw new Error('Missing #closing-price-chart container')
}

const options = {
  definition: closingPriceChart,
  height: 360,
  initialWidth: 640,
  ariaLabel: 'Apple closing price with first-quarter gaps',
  ariaDescription: 'First-quarter observations are intentionally omitted.',
}

const host = mountChart(container, options)

initialWidth is the deterministic fallback for server output, hidden containers, and the first frame before measurement. Once visible, the host uses ResizeObserver to follow the container.

4. Update the chart#

Host options only cover mounting concerns such as size and accessibility:

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

When data, visual options, focus, tooltips, keyboard policy, or animation change, create a new definition and pass it to host.update. In a framework component, memoize the complete definition against the values it captures. See Chart definitions.

5. Clean up#

host.destroy()

Destroying the host removes observers, event listeners, animations, tooltips, and chart markup. Framework adapters do this automatically during unmount.

What the declaration means#

• lineY(closingPrices, ...) chooses a line mark and keeps each source row as the interaction datum.
• x: 'Date' maps the source date field; the y accessor returns Close or an intentional gap.
• The unique date gives each observation stable positional identity across updates.
• D3 scale factories infer domains from mark channels and own mapping behavior.
• TanStack Charts copies those scales and assigns responsive pixel ranges.
• label, format, and grid configure the axis guide without changing the scale.
• Omitted margins are measured automatically from the rendered labels and titles.
• ariaLabel names the chart; pointer and keyboard focus use the same inferred points.

Read Grammar of Graphics for the full model, then browse the Example Gallery for complete compositions.