Reference lines

Add axis thresholds without changing the dataset. This feature belongs to @revolist/charts and can be used without Pivot or a grid.

Try it live

The dashed line marks a target of 100. Change the value below to move it. Reference lines span the plot along an axis, so they do not need two chart coordinates.

The reference is configured through the API. The drawing toolbar edits shapes; it is not a reference-line inspector.

Reset example annotations

Loading chart…

Inspect live chart state

The chart uses the native Charts renderer. Buttons outside the plot are example application controls calling the public API.

Complete chart setup with sample data

Install Charts using the installation guide, then run this setup after the host mounts. The data is illustrative. Additional actions for this tool are explained below.

<div id="chart" style="width:100%;height:500px"></div>

import { createChartFactory } from '@revolist/charts/core';
import { lineChart } from '@revolist/charts/line';
import { groupedColumnChart } from '@revolist/charts/grouped-column';
import { columnLineChart } from '@revolist/charts/column-line';

const rows = [
  {
    "date": 1767225600000,
    "month": "Jan",
    "revenue": 65,
    "costs": 45
  },
  {
    "date": 1769904000000,
    "month": "Feb",
    "revenue": 82,
    "costs": 50
  },
  {
    "date": 1772323200000,
    "month": "Mar",
    "revenue": 76,
    "costs": 48
  },
  {
    "date": 1775001600000,
    "month": "Apr",
    "revenue": 95,
    "costs": 65
  },
  {
    "date": 1777593600000,
    "month": "May",
    "revenue": 110,
    "costs": 72
  },
  {
    "date": 1780272000000,
    "month": "Jun",
    "revenue": 102,
    "costs": 68
  },
  {
    "date": 1782864000000,
    "month": "Jul",
    "revenue": 121,
    "costs": 80
  },
  {
    "date": 1785542400000,
    "month": "Aug",
    "revenue": 115,
    "costs": 76
  },
  {
    "date": 1788220800000,
    "month": "Sep",
    "revenue": 135,
    "costs": 89
  },
  {
    "date": 1790812800000,
    "month": "Oct",
    "revenue": 128,
    "costs": 85
  },
  {
    "date": 1793491200000,
    "month": "Nov",
    "revenue": 145,
    "costs": 92
  },
  {
    "date": 1796083200000,
    "month": "Dec",
    "revenue": 155,
    "costs": 100
  }
];
const mapping = {
  "category": {
    "field": "date",
    "label": "month"
  },
  "series": [
    {
      "field": "revenue",
      "label": "Revenue"
    },
    {
      "field": "costs",
      "label": "Costs"
    }
  ]
};
const createChart = createChartFactory([lineChart, groupedColumnChart, columnLineChart]);
const container = document.getElementById('chart')!;
const chart = await createChart({
  container,
  data: rows,
  mapping,
  "chartType": "line",
  "axes": {
    "x": {
      "scale": "time"
    }
  },
  "presentation": {
    "title": "Monthly performance",
    "subtitle": "Illustrative data · 2026",
    "legendPosition": "bottom"
  },
  "interaction": {
    "mode": "select",
    "selectionMode": "multiple"
  },
  "annotations": {
    "references": [
      {
        "id": "example",
        "color": "#6647f0",
        "kind": "line",
        "axis": "primary",
        "value": 100,
        "label": "Target",
        "lineDash": "dash"
      }
    ]
  }
});

// When the host unmounts:
// chart.destroy();

API and configuration

await chart.update({ annotations: { references: [{
  id: 'target', kind: 'line', axis: 'primary', value: 100,
  label: 'Target', color: '#6647f0', lineDash: 'dash',
}] } });

Support and behavior

Check the selected type’s getChartDefinition(type).annotations.axes before using references. Primary/secondary value references use numeric values; category-axis references use semantic paths or UTC time coordinates. An unconfigured secondary axis cannot be targeted.

Calculate a reference from the data

Use annotations.calculated for a mean, median or percentile line, or a population-standard-deviation band. The shared engine recalculates references from canonical finite values after updates and selection changes.

await chart.update({ annotations: {
  ...chart.model.annotations,
  calculated: [{
    id: 'mean', seriesId: 'revenue', statistic: 'mean',
    scope: 'selected', label: 'Selected average',
  }],
} });

Scopes are all (the chart dataset), visible (the viewport), or selected (semantic chart selection). Empty scopes omit the reference. Source totals and synthetic Others are excluded. IDs must also be unique across calculated references. The existing shape drawing toolbar does not author these calculations; applications configure them through the API. See the dedicated Analysis guide for methods, examples and limitations.

State and cleanup

Authored settings are available through chart.model. Updates replace whole settings objects: spread fields you want to retain, and await the returned promise before reading state or exporting. Destroy the controller when its host unmounts. Committed annotations appear in SVG/PNG/PDF output; CSV remains data-only. Shape IDs must be unique across shapes, references and datum notes. { annotations: {} } clears annotations and editing opt-in.

All chart tools · Chart types · Data & Configuration