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 z group.

const mark = lineY(rows, {
  x: 'date',
  y: 'value',
  z: 'series',
  key: 'id',
  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 z, 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.

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',
      key: 'id',
    }),
  ],
  x: { scale: xScale },
  y: { scale: yScale },
})

Use matching channels and scales when the two layers must align. Set stable keys independently on every interactive layer.