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.

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.

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 window transform beside the definition, keep the original time domain, and name the window in surrounding text or a legend.

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.

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

const bands = window(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 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.

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.