Dynamic Data and Animation

Definition identity is the application update boundary. A framework memo captures the current data and options; Charts rebuilds the scene when that definition changes or when the chart surface changes size.

React

tsx

function RankingChart({ rows, metric, accent }: Props) {
  const definition = useMemo(() => {
    const ranked = rankRows(rows, metric)

    return defineChart({
      animate: { duration: 280, easing: 'ease-out' },
      chart: ({ width }) => ({
        marks: [
          barX(ranked, {
            x: 'value',
            y: 'label',
            fill: accent,
          }),
        ],
        x: {
          scale: scaleLinear,
          nice: true,
          axis: { ticks: { count: width < 420 ? 4 : 7 } },
        },
        y: {
          scale: () => scaleBand<string>().padding(0.1),
        },
      }),
    })
  }, [rows, metric, accent])

  return <Chart definition={definition} ariaLabel="Revenue ranking" />
}

Use the framework's native equivalent: computed, createMemo, $derived, Angular computed, or Octane useMemo.

Vanilla

host.update({
  ...options,
  definition: createRankingDefinition(nextRows, nextMetric, nextAccent),
})

Stable keys

Built-in marks first use an explicit key, then a unique datum.id, then a unique nested datum.data.id. Marks can also infer identity from semantic positional channels:

barX(rows, {
  x: 'value',
  y: 'label',
})

Here barX uses the unique y value when rows have no id. barY uses x; lineY and areaY use x; areaX uses y; rects and cells use their x/y interval tuple. Dots and text try x, then y, then their x/y tuple. Inference is scoped to each group and falls back to array position when a candidate is incomplete or duplicated. Development builds warn once for each affected mark instance.

Supply key when the inferred value is not the entity's identity or can change independently of it. Stable identity preserves surviving SVG elements, focused points, and transition continuity.

Lightweight SVG tweening

animate accepts true or:

duration: milliseconds;
easing: linear, ease, ease-in, ease-out, ease-in-out, or a function from normalized progress to normalized progress;
respectReducedMotion: defaults to true;
resize: defaults to false, so responsive relayout does not repeatedly restart animation.

Numeric geometry and compatible path data interpolate. Entering and exiting nodes reconcile by key. If an update interrupts a transition, it begins from the geometry currently painted on screen.

Static SVG, server rendering, and createChartScene do not include animation.

Use this path when a small default-SVG tween is enough. It has no spring solver, definition-local timing cascade, entrance choreography, or retained velocity.

Optional tween and spring motion

Use motion() when animation quality is part of the chart contract:

import { motion } from '@tanstack/charts/motion'
import { mountChartRenderer } from '@tanstack/charts/renderer'

const definition = defineChart({
  motion: {
    transition: { type: 'spring', stiffness: 170, damping: 18, mass: 1 },
  },
  marks: [
    lineY(rows, {
      x: 'date',
      y: 'actual',
      key: 'id',
    }),
    lineY(rows, {
      x: 'date',
      y: 'forecast',
      key: 'id',
      motion: { transition: { type: 'spring', mass: 1.25 } },
    }),
  ],
  x: { scale: scaleUtc },
  y: { scale: scaleLinear },
})

const host = mountChartRenderer(container, {
  definition,
  renderer: motion(),
  width: 640,
  height: 360,
  ariaLabel: 'Actual and forecast revenue',
})

Each host has one animation owner. The default SVG renderer uses animate. When motion() is the renderer, it ignores animate and uses motion declarations from the definition. A motion declaration configures the motion renderer; it does not select it.

Motion declarations can live on the chart, a mark, an axis, its ticks, tick labels, or axis label. A callback can specialize enter, update, and exit by series or datum:

barY(rows, {
  x: 'month',
  y: 'revenue',
  key: 'id',
  motion(context) {
    if (context.phase === 'enter') {
      return { delay: context.datumIndex * 35 }
    }
    if (context.datum?.status === 'forecast') {
      return { transition: { type: 'tween', duration: 240 } }
    }
  },
})

Same-type partial transitions inherit omitted properties. Springs use physical stiffness, damping, and mass; duration is not a spring parameter. Rapid retargeting preserves the currently painted value and velocity. Keyed interaction points move with the presentation geometry rather than jumping to the next scene.

Spring updates always retarget immediately; a returned update delay is ignored so incoming momentum cannot freeze. Use delays for spring enter/exit choreography or any tween phase.

The renderer grows entering bars from their semantic baseline, reveals entering line groups, staggers bar entrances, morphs compatible numeric SVG geometry, and fades incompatible keyed topology. Authored delay replaces automatic staggering for that target.

motion() respects reduced motion and does not animate resize-only updates by default. It adopts server-rendered SVG without replaying entrance motion. Static SVG and Canvas accept the same definitions but paint the final state.

See the Motion reference for the complete cascade, types, focus-state transitions, compatibility limits, and standalone spring sampler.