Text, Frame, and Facet Marks

text annotates scaled positions, frame paints the resolved inner chart bounds, and facet composes complete child specs into responsive small multiples.

import { facet, facetChart, frame, lineY, text } from '@tanstack/charts'

text

text(rows, {
  x: 'date',
  y: 'value',
  text: 'label',
  z: 'series',
  dy: -8,
})

function text<TDatum>(
  source: Iterable<TDatum>,
  options?: TextOptions<TDatum>,
): ChartMark<TDatum, InferredX, InferredY>

Options

Labels use a middle baseline. Null or undefined text skips the row; the default for a null datum is an empty string. Invalid x/y values also skip the row.

The interaction point is at the offset label origin. Its semantic values remain the original x/y channels. Without an explicit key, text tries a unique top-level or nested data.id, then x, y, and the x/y tuple. Supply key when positions can change while the same label should reconcile across updates.

frame

frame draws a background, border, or both around the final inner chart bounds:

frame({
  fill: 'color-mix(in srgb, currentColor 3%, transparent)',
  strokeOpacity: 0.25,
  radius: 8,
})

function frame(options?: FrameOptions): ChartMark<never, never, never>

frame materializes no scale channels and emits no interaction points. Put it before data marks when it should paint behind them.

facet

facet groups source rows by a key and renders one complete child chart spec per group inside the parent chart bounds.

facet(rows, {
  by: 'region',
  columns: 3,
  minWidth: 220,
  gap: 16,
  label: (region) => `Region: ${region}`,
  chart(groupRows) {
    return {
      marks: [lineY(groupRows, { x: 'date', y: 'value' })],
      scales: {
        x: { scale: makeXScale(groupRows) },
        y: { scale: makeYScale(groupRows), grid: true },
      },
    }
  },
})

function facet<TDatum, TChildSpec extends ChartSpec>(
  source: Iterable<TDatum>,
  options: FacetOptions<TDatum, TChildSpec>,
): ChartMark<ChartSpecDatum<TChildSpec>>

Options

FacetChartContext.key is the materialized value for the current group.

Facet preserves first-seen group order and original row order within each group. Non-string and non-number by results are skipped.

Automatic columns are:

floor((availableWidth + gap) / (minWidth + gap))

with a minimum of one. Rows are then derived from group count. Visible facet labels reserve 22 pixels above every child plot.

Outer axes

With more than one child and guides enabled, the default axes: 'outer' renders y ticks on the first column, x ticks on the final occupied row, and one shared title per dimension.

Outer axes require compatible cells:

• x and y resolved scale types, domains, ticks, labels, and direction match
• axis label, label offset, and tick rotation match
• foreground and muted theme tokens match
• no child provides its own margin
• no child provides a color legend
• no child sets guides: false

An incompatible facet throws with guidance to use axes: 'cell'. This fail-fast behavior prevents a shared axis from implying a comparison the child scales do not support.

When every child sets guides: false, or there is only one child, facet uses the cell rendering path even if axes is omitted.

Cell axes

Set axes: 'cell' when groups need independent scales, guide options, margins, or legends:

facet(rows, {
  by: 'region',
  axes: 'cell',
  chart: (groupRows) => buildIndependentSpec(groupRows),
})

Every child compiles at its own cell dimensions with the parent's text measurement. Compilation errors are wrapped with the facet and cell key.

Interaction

Child ChartPoint coordinates are offset into the parent scene. Point keys are prefixed with facet and group identity, so equal child keys remain unique across cells. Datum, semantic x/y values, group, group label, and paint are preserved. The facet's output datum type comes from the marks returned by chart; grouping rows do not replace a child point's original datum. Motion callbacks receive that same child datum type.

The facet mark itself has intentionally opaque positional types because each child may return a different mark composition. Its child scale domains do not participate in the parent x/y scales.

facetChart

facetChart wraps a facet mark in a complete static definition:

const definition = facetChart(rows, {
  by: 'region',
  chart: (groupRows) => buildSpec(groupRows),
})

function facetChart<TDatum, TChildSpec extends ChartSpec>(
  source: Iterable<TDatum>,
  options: FacetOptions<TDatum, TChildSpec>,
): StaticChartDefinition<ChartSpecDatum<TChildSpec>>

The wrapper sets:

const specification = {
  marks: [facet(source, options)],
  margin: 0,
}

Use facet directly when the small multiples must be layered with other parent-scene marks. Use facetChart for the usual standalone chart.