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, lineY } 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.

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#

When y1 is omitted, the y channel materialization carries an includeZero hint. The caller still owns the scale domain. Explicit y1, including a constant, removes that hint.

Input order and null-gap behavior match lineY. 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#

When x1 is omitted, the x channel carries the includeZero hint. 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 and D3.

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.