DOM Host

mountChart is the framework-neutral default SVG browser host. It owns responsive measurement, scene updates, keyed SVG reconciliation, animation, pointer and keyboard interaction, native tooltips, font relayout, and cleanup.

import { defineChart } from '@tanstack/charts'
import { mountChart } from '@tanstack/charts/dom'

Signature#

function mountChart<
  TDatum,
  TXValue extends ChartValue = ChartValue,
  TYValue extends ChartValue = ChartValue,
>(
  container: HTMLElement,
  initialOptions: ChartHostOptions<TDatum, TXValue, TYValue>,
  runtime?: ChartRuntime<TDatum, TXValue, TYValue>,
): ChartHost<TDatum, TXValue, TYValue>

The optional runtime is for adapters or advanced applications that already rendered an initial scene. Ownership transfers to the host: host.destroy() also destroys that runtime. In ordinary vanilla use, omit it.

Basic use#

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

const host = mountChart(container, options)

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

host.destroy()

Application changes use a new definition:

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

The definition identity is the application update boundary. Responsive definitions still rebuild when their resolved surface size changes.

Renderer-neutral and Canvas hosts#

Use the lower-level host when the surface is not necessarily SVG:

import { canvasChartRenderer } from '@tanstack/charts/canvas'
import { mountChartRenderer } from '@tanstack/charts/renderer'

const host = mountChartRenderer(container, {
  definition: defineChart(definition, { tooltip: true }),
  renderer: canvasChartRenderer,
  ariaLabel: 'Weekly revenue',
})

mountChartRenderer accepts ChartRendererHostOptions and returns a ChartRendererHost. Its host lifecycle matches mountChart, but renderer is required and onRender receives a ChartRendererRenderContext containing the live ChartSurface.

For the built-in Canvas renderer, mountCanvasChart from @tanstack/charts/canvas removes the explicit renderer option and returns a CanvasChartHost. Both hosts preserve the same update, getScene, and destroy interaction model.

Host options#

The default SVG host requires definition and ariaLabel.

The definition owns these chart behaviors:

Definition keyboard: false takes precedence over host tabIndex. A negative custom tab index can keep chart keyboard behavior available for programmatic focus without placing the chart in the normal tab order.

Interaction options are detailed in Focus and interaction. Renderer and animation options are detailed in Rendering and export.

Responsive sizing#

When width is absent, the host reads the container's bounding width and observes it with the container document's ResizeObserver.

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

The fallback order is:

1. explicit width
2. positive container width
3. initialWidth
4. 640

Height is explicit height, then a positive finite aspectRatio, then 320. The host schedules responsive relayout on the document's animation frame and skips renders when the measured width has not changed. Resize relayout commits immediately by default; set animate.resize to true to animate it.

The host temporarily assigns position: relative when the container's computed position is static, because local native tooltips are absolutely positioned inside it. Definition tooltip.portal: true instead places the tooltip in the browser top layer through a manual Popover, or directly under the ownerDocument body as a fixed fallback, and positions it against the viewport. destroy restores the previous inline position when the host owned that change and removes its tooltip.

Font measurement#

The default DOM measurer inherits the container's computed font family, style, stretch, weight, direction, and letter spacing. Measurements are cached. The host clears that cache and relayouts when:

• the inherited font signature changes during update
• the document font set emits loadingdone

Pass measureText to own the geometry or to make browser and nonbrowser output use the same metrics. See Scales, guides, and color for the function contract.

ChartHost#

interface ChartHost<
  TDatum = unknown,
  TXValue extends ChartValue = ChartValue,
  TYValue extends ChartValue = ChartValue,
> {
  update(options: ChartHostOptions<TDatum, TXValue, TYValue>): void
  getScene(): ChartScene<TDatum, TXValue, TYValue>
  destroy(): void
}

update#

update replaces the complete option set. Keep required options in every call. It renders synchronously when definition identity, size, accessibility, renderer, keyboard, ID, or text measurement changes. Interaction callbacks, tooltip formatting, focus strategy, animation settings, and the spatial index can update without rebuilding the scene.

An interrupted animated render is canceled before the next reconciliation. When the focused observation can be restored after a scene rebuild, focus and grouped focus are repainted against its new coordinates.

getScene#

Returns the current compiled scene. It is useful for aligned application UI, diagnostics, or custom interaction. Treat it as immutable.

destroy#

destroy is idempotent. It disconnects resize and font listeners, cancels scheduled work and animation, removes interaction listeners, clears the container, and releases an inline positioning change owned by the host. A destroyed host ignores later updates.

Browser ownership#

The DOM host requires a live HTMLElement and its owning document. For static or server rendering, compile a scene and render SVG without mounting; see Runtime and scene and Rendering and export.