---
title: "Reference lines and bands"
description: "spec.references draws lines and bands across the plot at values of the value axis."
canonical_url: "https://tiptap.dev/docs/diagrams/charts/references"
---

# Reference lines and bands

spec.references draws lines and bands across the plot at values of the value axis.

## Quick start

Set them with `updateChartSpec`. The list replaces the one before, 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

| Field        | Type                              | Description                                                                    |
| ------------ | --------------------------------- | ------------------------------------------------------------------------------ |
| `value`      | `number`                          | A line at this value                                                           |
| `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** lie over the series.
- **Every label** lies over the series.
- **On a chart with a `background`**, a label gets an outline in that color so it reads across a
  bar.
- **A reference beyond 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 one.

## Which charts and Renderers draw them

References apply to line, bar, area, scatter and combo charts.

| Renderer | Draws them                                                                                                      |
| -------- | --------------------------------------------------------------------------------------------------------------- |
| ECharts  | Yes                                                                                                             |
| d3       | Yes                                                                                                             |
| Mermaid  | No, so such a chart goes to another Renderer                                                                    |
| Word     | No. Word charts have no reference lines, so `exportDocx` writes the chart as a picture and says so in its notes |