---
title: "Reference lines and bands"
description: "A reference line marks one value across the plot, such as a target."
canonical_url: "https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/references"
---

# Reference lines and bands

A reference line marks one value across the plot, such as a target.

## Quick start

Set the references with `updateChartSpec`. The new list replaces the old one, and `undefined`
removes it.

```ts
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`:

| Field        | Type                              | Description                                                                    |
| ------------ | --------------------------------- | ------------------------------------------------------------------------------ |
| `value`      | `number`                          | A line at this value. Wins over `from` and `to`                                |
| `from`, `to` | `number`                          | A band between these values, instead of `value`                                |
| `label`      | `string`                          | Written above a line, or inside a band at its top                              |
| `labelAt`    | `'start' \| 'end'`                | Which end of the category axis the label stands at. Default: `'end'`           |
| `color`      | `string`                          | A CSS color. A band is a light tint of it. Without it, the theme's label color |
| `line`       | `'solid' \| 'dashed' \| 'dotted'` | A line only. Default: `'dashed'`                                               |
| `width`      | `number`                          | A line only: 0.5 to 4 CSS pixels. Default: 1.5                                 |

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 every label lie over the series. On a chart with a
`background`, a label gets an outline in that color, so you can read it across a bar.

A reference outside the data widens the value axis to show it. On horizontal bars, the
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. The
[ECharts](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/echarts.md#chart-types) and
[D3](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/d3.md#chart-types) Renderers draw them. The Mermaid Renderer declines
such a chart, see its [limits](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/mermaid.md#limits).

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