Reference lines and bands

A reference line marks one value across the plot, such as a target. A band marks a range between two values, such as a range to stay in. Both belong to the value axis and are stored in spec.references.
New tab

Quick start

On a selected chart, as after the Charts quick start, updateChartSpec sets the references. The new list replaces the old one, and undefined removes it.

editor.commands.updateChartSpec({
  spec: {
    references: [
      { value: 200, label: 'Target', color: '#dc2626' },
      { from: 80, to: 120, label: 'Corridor', color: '#16a34a' },
    ],
  },
})

Fields

Each entry of spec.references is a ChartReference:

FieldTypeDefaultDescription
valuenumberNoneA line at this value. Wins over from and to
from, tonumberNoneA band between them, stored low to high
labelstringNoneAbove a line, or inside a band at its top. Up to 200 characters
labelAt'start' | 'end''end'Which end of the category axis the label stands at
colorstringThe theme's label colorA CSS color. A band is a light tint of it
line'solid' | 'dashed' | 'dotted''dashed'A line only
widthnumber1.5A line only: 0.5 to 4 CSS pixels

An entry with neither a value nor two different from and to values is dropped. A chart keeps at most 20 entries.

How they are drawn

Bands lie behind the series, lines and labels over them. With a background, a label gets an outline in that color, so it reads across a bar.

A reference outside the data widens the value axis. On horizontal bars, references stand upright. On a combo chart with a second axis, they belong to the left axis.

Which charts and Renderers draw them

References apply to line, bar, area, scatter and combo charts. ECharts and D3 draw them, and the Mermaid Renderer declines such a chart, see its limits.

Word charts have no reference lines, so exportDocx writes the chart as an image and says so in its notes, see Word.