Types

TanStack Charts is inference-first. A mark's source data and channel selectors flow through its definition into scales, axis formatters, host and adapter callbacks, focus callbacks, and selection callbacks. Normal application code should not cast chart definitions or supply adapter generics.

Browser applications can import types from the package root. Platform-neutral libraries can import the same definition, mark, scene, runtime, focus, and tooltip-model contracts from @tanstack/charts/types; DOM host and renderer types remain available from the root.

Values and channels#

type ChartValue = number | string | Date
type ChartKey = string | number

type ChannelAccessor<TDatum, TValue> = (
  datum: TDatum,
  index: number,
  data: readonly TDatum[],
) => TValue

type Channel<TDatum, TValue> =
  ChannelField<TDatum, TValue> | ChannelAccessor<TDatum, TValue>

type VisualChannel<TDatum, TValue> = TValue | ChannelAccessor<TDatum, TValue>

The corresponding public type names are Channel, ChannelAccessor, and VisualChannel.

A Channel accepts only datum keys whose declared values are compatible with the channel, or an accessor that derives a value from the row, index, and full readonly data array. A VisualChannel replaces the field-name form with a constant: it accepts either one constant value or an accessor.

import { lineY } from '@tanstack/charts'

interface Row {
  date: Date
  value: number
  label: string
  series: 'actual' | 'forecast'
}

lineY(rows, {
  x: 'date', // Date
  y: 'value', // number
  z: 'series',
  stroke: (row) => (row.series === 'actual' ? '#2563eb' : '#60a5fa'),
})

ChannelField, ChannelOutput, OptionChannelOutput, WidenChartValue, and ChartAxisValue are exported for extension authors. Literal chart values widen to their semantic primitive so a literal row does not produce an unusably narrow scale or callback type.

Inference path#

source datum
  → mark channel outputs
  → ChartMark point and scale value types
  → ChartSpec axis requirements and definition datum/x/y unions
  → axis scale and formatter types
  → host and adapter callback types

Marks in one chart may have different datum types. The definition exposes their union. TypeScript narrowing is therefore required when a callback handles heterogeneous layers.

ChartMarkScaleX and ChartMarkScaleY also control the chart shape. A materialized scale value makes that axis required. never makes it optional and null-only, so positionless and one-dimensional charts do not carry phantom scale configuration.

Rect and custom interval marks can distinguish materialized scale values from interaction point values. The exported extractors are:

ChartMarkDatum, ChartSpecDatum, ChartSpecXValue, and ChartSpecYValue are available from the root entry point. The four ChartMarkPoint* and ChartMarkScale* extractors below come from the exceptional @tanstack/charts/mark/scale-values subpath.

ChartMarkX and ChartMarkY remain exported as deprecated aliases of the point extractors. New code should use the explicit names.

Stateful mark presentation uses ChartMarkStateContext as one object bag for the datum, index, data, point, focus, pointer, and matching helper. A ChartMarkStateSelector handles the common declarative cases, while callbacks can return any ChartMarkStateValue. ChartMarkStateStyle is the complete style vocabulary; ChartDotStateStyle, ChartBarStateStyle, ChartRectStateStyle, ChartLineStateStyle, ChartAreaStateStyle, and ChartTextStateStyle narrow it to properties each mark can render.

Definitions#

The complete overloads and runtime rules are in Chart Definition API.

Marks and scenes#

Scene geometry and interaction point fields are documented in Runtime and scene.

Scene-node types#

SceneNode is the union of:

• SceneGroup
• SceneRule
• ScenePolyline
• SceneArea
• SceneDot
• SceneRect
• SceneLabel

SceneStyle is shared presentation. ChartSize, ChartBounds, ChartMargin, ChartLayoutOptions, ChartTextMeasurer, ChartTextMeasureOptions, and ChartTextMetrics describe scene and text geometry.

See Scene nodes.

Scale, guide, color, and theme types#

See Scales, guides, and color.

Host and runtime types#

See DOM host and Runtime and scene.

Focus and tooltip types#

See Focus and interaction.

Rendering types#

See Rendering and export.

Capability-specific types#

Types tied to optional capabilities are documented with the API that owns their behavior:

• @tanstack/charts/adapter: ChartAdapter, ChartAdapterLayout, and ChartAdapterLayoutOptions. See Adapter controller.
• @tanstack/charts/canvas: CanvasChartRendererOptions, CanvasChartRenderer, CanvasChartSurface, CanvasChartHostOptions, and CanvasChartHost. See Canvas renderer.
• @tanstack/charts/export: SerializeChartSvgOptions and RenderChartPngOptions. See SVG serialization and browser image export.
• @tanstack/charts/geo: GeoProjectionContext, GeoProjectionDescriptor, GeoProjectionInput, and GeoShapeOptions. See Geo shape.
• @tanstack/charts/polar: PolarOptions, PolarMark, PolarGuide, PolarGuideScene, PolarAngleOptions, PolarRadiusOptions, PolarResolvedScale, PolarLayoutContext, PolarLength, PolarGuideLabelContext, PolarGuideLabelOption, RadialArcOptions, RadialLineOptions, RadialAreaOptions, RadialDotOptions, RadialTextOptions, RadialRuleOptions, RadialGridOptions, and AngleGridOptions. See Polar marks.

Mark option types#

Every built-in mark exports its options type from the root and its granular subpath:

• LineYOptions, AreaYOptions, AreaXOptions, AreaXCurve
• BarYOptions, BarXOptions
• DotOptions, HexagonOptions
• RectOptions, CellOptions
• RuleXOptions, RuleYOptions
• LinkOptions, ArrowOptions, VectorOptions, VectorAnchor
• TickXOptions, TickYOptions
• TextOptions, TextAnchor
• FrameOptions
• FacetOptions, FacetAxes
• ColorLegendOptions, ColorGradientLegendOptions

Their public fields and defaults are owned by the mark reference and legend reference.

Correcting a type error#

When a normal chart requires as, first check:

1. Is the row interface accurate, including nullable values?
2. Is the selected field compatible with the mark channel?
3. Does the configured scale domain accept the inferred semantic value?
4. Does the definition capture values with their exact application types?
5. Are mixed mark datum or value unions being narrowed honestly?
6. Is a custom mark declaring its datum and point values at createMark?

Use an assertion only at a genuinely unchecked external boundary. Do not cast the definition or framework props to bypass a mismatch.