Faceting and Composition

Composition is the main extension mechanism in TanStack Charts. Marks share a chart specification, scales, theme, and responsive plot rectangle. More complex views combine those same primitives instead of switching to a separate component family.

Layer marks#

Marks are rendered in array order. Put broad background geometry first and annotations or direct labels last:

const definition = defineChart({
  marks: [
    ruleY([0]),
    areaY(rows, { x: 'date', y1: 'low', y2: 'high' }),
    lineY(rows, { x: 'date', y: 'median' }),
    dot(highlights, { x: 'date', y: 'median' }),
    text(labels, { x: 'date', y: 'median', text: 'label' }),
  ],
  x,
  y,
})

Each mark may consume a different datum type. The resulting chart interaction type is the honest union of those datum types. Use ordinary TypeScript narrowing when a callback handles several layers.

The canonical grammar is described in Marks and Layering.

Facet one view by a field#

facetChart repeats a mark composition for each group and returns a complete guide-free outer definition:

const definition = facetChart(rows, {
  by: 'group',
  columns: 2,
  gap: 20,
  axes: 'outer',
  chart(data) {
    return {
      marks: [dot(data, { x: 'x', y: 'y' })],
      x: { scale: scaleLinear().domain(sharedX) },
      y: { scale: scaleLinear().domain(sharedY) },
    }
  },
})

Use facet(rows, options) instead when the repeated panels need to be one mark inside a larger custom definition.

The default axes: 'outer' draws shared guides around the complete facet grid. Use axes: 'cell' when each panel needs its own guides. Cell axes and incompatible independent scales cannot be presented as one shared outer axis; choose the option that matches the comparison.

Share domains intentionally#

Shared scales make position comparable across panels. Independent domains make local variation easier to see but can exaggerate differences.

Build shared domains once and pass configured scales to every facet. When a panel deliberately uses an independent domain, label that policy in the surrounding UI.

The Scales and D3 page owns scale construction and responsive range rules.

Compose distinct views#

Not every composition is a facet. A focus-and-context chart, scatterplot with marginal histograms, or chart-plus-table contains views with different roles. In that case:

1. Keep each chart definition independent.
2. Store shared selection or viewport in application state.
3. Give each view its own accessible name.
4. Convert semantic state into each view's configured domains.
5. Align overlays from each resolved scene.chart.

Do not coordinate charts by querying or mutating their SVG nodes.

Embedded regions and custom layout#

When several plot regions must live inside one SVG, a custom mark can render scene groups with explicit translations and clips. Use that only when one responsive scene is materially better than several accessible chart hosts.

The Custom Marks and Renderers guide explains the scene-node protocol. The Responsive Charts guide explains how to base region geometry on the final chart bounds.

Composition checklist#

• Layer order reflects visual occlusion and reading order.
• Each mark keeps its natural data shape and stable keys.
• Shared scales are used only where direct positional comparison is intended.
• Facet axis policy is explicit.
• Each independently interactive view has its own accessible name.
• Shared state is semantic application state, not DOM state.
• Dense dashboards destroy hosts and listeners when panels unmount.