Lines and Areas

Lines answer how a value changes across an ordered domain. Areas add a second meaning: distance from a baseline or the span between two boundaries. Use that extra area only when the reader should compare magnitude, accumulation, or an interval—not merely because a filled chart looks stronger.

Choose the comparison#

The x domain must have a meaningful order. Do not connect nominal categories just because they appear in an array.

Start with one ordered series#

Use one line when the first task is reading change over a shared sequence. Points keep the individual observations available for focus and tooltips.

import { defineChart, lineY } from '@tanstack/charts'
import { scaleLinear } from '@tanstack/charts/scales/linear'
import { scalePoint } from '@tanstack/charts/scales/point'

const rows = [
  { month: 'Jan', downloads: 42 },
  { month: 'Feb', downloads: 58 },
  { month: 'Mar', downloads: 51 },
  { month: 'Apr', downloads: 73 },
  { month: 'May', downloads: 81 },
]

const chart = defineChart({
  marks: [
    lineY(rows, {
      x: 'month',
      y: 'downloads',
      points: true,
      stroke: '#2563eb',
      lineCap: 'butt',
    }),
  ],
  scales: {
    x: { scale: () => scalePoint<string>().padding(0.2) },
    y: {
      scale: scaleLinear,
      nice: true,
      grid: true,
      axis: { label: 'Downloads (thousands)' },
    },
  },
})

export default chart

lineCap: 'butt' ends the stroke at each path endpoint. Omit it to retain the default round endpoints. lineX accepts the same lineCap and lineJoin options.

Compare several series from a common baseline#

Indexing each series to its first observation compares relative change when the original magnitudes are not directly comparable. Direct end labels reduce the work of matching line colors to a separate legend.

Indexed Multi Line

EditRun

Prepare the indexed values in the application, state the baseline, and retain the original values for exact-value disclosure. Use a stable series channel so color, path grouping, focus, and updates agree on identity. Data and Channels covers series grouping, while Legends and Color explains when a separate legend is the better choice.

Show a derived trend honestly#

A moving average is a derived series, not a visual curve setting. Prepare the rolling values with the public rollingWindow transform beside the definition, keep the original time domain, and name the rolling window in surrounding text or a legend.

Moving Average Line

EditRun

Changing interpolation only changes the path between observations. It does not perform smoothing or create evidence between samples. See Data Transforms for rolling windows and reducers.

Compare two boundaries at their exact crossings#

A difference chart separates the intervals where a primary series is above or below a comparison. Keep any rolling statistic or forecast calculation in data preparation, then give both boundaries to differenceY:

differenceY(rows, {
  x: 'Date',
  y1: 'average',
  y2: 'Close',
  positiveFill: '#16a34a',
  negativeFill: '#dc2626',
  comparisonStroke: '#475569',
})

The mark finds each sign change, interpolates the exact crossing, and owns the positive area, negative area, comparison line, and primary line. Application code does not need to prepare sign runs or duplicate boundary rows.

The Overview shows the complete rendered Apple closing-price example. See Difference Marks for transposed differenceX, gap behavior, fill suppression, lineage, and interaction.

Add context with an interval#

A Bollinger band combines a rolling center line with an interval derived from local variation. The band is context for the observed series; it is not a confidence interval unless the underlying calculation actually defines one.

Bollinger Band

EditRun

Compute the rolling statistics once and share those rows between the interval and center line:

const bands = rollingWindow(aapl, {
  size: 20,
  orderBy: 'Date',
  anchor: 'end',
  partial: false,
  outputs: {
    meanClose: { value: 'Close', reduce: 'mean' },
    closeDeviation: { value: 'Close', reduce: deviation },
  },
})

areaY(bands, {
  x: 'Date',
  y1: (row) => row.meanClose - row.closeDeviation * 2,
  y2: (row) => row.meanClose + row.closeDeviation * 2,
})

lineY(bands, { x: 'Date', y: 'meanClose' })

The rolling-window length, estimator, and multiplier are authored statistical meaning. The transform owns ordering and source lineage; the area owns interval geometry. See Line and Area Marks for the channel contracts.

Annotate selected observations#

Annotations should explain a small number of meaningful points. Selecting the minimum and maximum in data preparation makes the intent auditable and avoids placing a text label on every observation.

Select Extrema

EditRun

Layer dots and text over the same scales rather than baking labels into a line renderer. Marks and Layering explains why separate layers remain easier to update and extend.

Production checks#

• Preserve missing values when a gap is meaningful. The Quick Start demonstrates an explicit line gap.
• Use a temporal scale for dates and define the domain in application data semantics, as described in Scales.
• Preserve row IDs or unique positions across updates, and group series with z; supply key only when the mark cannot infer identity. See Dynamic Data and Animation.
• Let automatic layout measure tick labels, then verify the smallest container in Responsive Charts.
• Use position, labels, or line treatment in addition to color when a distinction is essential. See Accessibility.