Line and Area Marks

Line and area marks consume an iterable directly. Channels may be compatible field names or accessors. Rows whose required positional value is null, undefined, invalid, or nonfinite create gaps instead of connecting across missing data.

import {
  areaX,
  areaY,
  defineChart,
  lineX,
  lineY,
  stack,
} from '@tanstack/charts'

lineY#

lineY connects consecutive valid rows within each path group. An explicit z defines the groups. When z is omitted and color is present, color defines them.

const mark = lineY(rows, {
  x: 'date',
  y: 'value',
  z: 'series',
  points: true,
})

function lineY<TDatum>(
  source: Iterable<TDatum>,
  options?: LineYOptions<TDatum>,
): ChartMark<TDatum, InferredX, number>

Options#

Input order is path order. Sort rows before creating the mark when semantic x order differs from input order. A null row flushes the current segment; later valid rows begin a new segment in the same group.

Each valid row emits one interaction point at its scaled x/y coordinate. groupLabel is the string form of the effective path group, or the mark ID without a group.

lineX#

lineX is the transposed line mark. It connects numeric x values along a numeric, categorical, or temporal y channel:

const mark = lineX(rows, {
  x: 'value',
  y: 'category',
  z: 'series',
  points: true,
})

function lineX<TDatum>(
  source: Iterable<TDatum>,
  options?: LineXOptions<TDatum>,
): ChartMark<TDatum, number, InferredY>

Its options transpose lineY: x is the numeric value channel and defaults to a numeric datum; y is the longitudinal ChartValue channel and defaults to row index. Identity falls back to y, invalid rows create segment gaps, and input order remains path order. Grouping, paint, points, curves, states, and motion use the same contract. Line interaction follows y affinity so keyboard and pointer traversal match the longitudinal axis.

areaY#

areaY fills between a numeric upper channel and a numeric lower baseline along x.

const mark = areaY(rows, {
  x: 'date',
  y1: 'low',
  y2: 'high',
  z: 'series',
})

function areaY<TDatum>(
  source: Iterable<TDatum>,
  options?: AreaYOptions<TDatum>,
): ChartMark<TDatum, InferredX, number>

Options#

Without explicit endpoints, repeated x positions stack by series. z defines series; a discrete color channel may infer it when z is absent. Use layout: stack(options) for explicit order, reversal, normalization, centering, or wiggle offset. Supplying y1 or y2 opts out and preserves authored interval boundaries.

Use order: 'inside-out' with offset: 'wiggle' for nonnegative streamgraphs. Inside-out order follows series peaks and totals. The completed wiggle stack is translated once so the global minimum start is zero; individual positions are not rebased. Positions and series retain first-seen order, and a missing position/series pair contributes zero to layout without emitting a synthetic point.

Input order and null-gap behavior match the line marks. Each valid row emits one point at the upper y2/y value, not at the lower baseline.

areaX#

areaX is the transposed interval area: it fills between left and right numeric x values along y.

const mark = areaX(rows, {
  y: 'category',
  x1: 'minimum',
  x2: 'maximum',
  z: 'series',
})

function areaX<TDatum>(
  source: Iterable<TDatum>,
  options?: AreaXOptions<TDatum>,
): ChartMark<TDatum, number, InferredY>

Options#

Without explicit endpoints, repeated y positions stack by series. Supplying x1 or x2 opts out and preserves authored interval boundaries. Each valid row emits one point at its right x2/x value.

Line and area paths have one paint value. When both channels are present, z wins for grouping and color may supply a different semantic paint value. Keep color constant within each explicit z group; the first row supplies the path color.

Curves#

Line and area marks accept a small path-generation contract rather than bundling interpolation algorithms:

interface ChartCurve {
  line(points: readonly (readonly [number, number])[]): string
  area(
    top: readonly (readonly [number, number])[],
    bottom: readonly (readonly [number, number])[],
  ): string
}

interface AreaXCurve {
  areaX(
    right: readonly (readonly [number, number])[],
    left: readonly (readonly [number, number])[],
  ): string
}

Optional adapters are available:

import { d3AreaXCurve } from '@tanstack/charts/d3/area-x'
import { d3Curve } from '@tanstack/charts/d3/shape'

They accept a supplied curve factory and return the corresponding TanStack contract. Which granular D3 module to install and why these algorithms remain injected is documented once in Scales.

Layering area and line#

Area marks do not automatically draw their upper line. Compose the layers:

const definition = defineChart({
  marks: [
    areaY(rows, {
      x: 'date',
      y: 'value',
      z: 'series',
      fillOpacity: 0.16,
    }),
    lineY(rows, {
      x: 'date',
      y: 'value',
      z: 'series',
    }),
  ],
  x: { scale: xScale },
  y: { scale: yScale },
})

Use matching channels and scales when the two layers must align. Identity inference is evaluated independently for every interactive layer; supply a key only where its automatic candidate is not stable.