Reference lines
Add fixed targets and calculated statistics to chart axes.
Reference lines mark a meaningful position on an axis. Use a fixed reference for a target, threshold, or event. Use a statistic when the line should be calculated from the chart's values and update with the data.
References are native chart semantics rather than independent drawing layers. Their values, labels, domains, filtering, and formatting follow the same compiled chart as every other output.
Fixed references
Categorical charts support fixed references on the category or value axis:
{
"type": "value",
"axis": "value",
"value": 150,
"label": {
"content": ["text"],
"text": "Target"
}
}A category reference identifies one valid category position. A value reference identifies one number on the quantitative axis. Scatter references use axis: "x" | "y" and accept values compatible with that axis's scale.
Column, bar, line, area, and scatter charts support references. Pie charts and ranged bars or columns do not.
Calculated references
A statistic reference calculates average, median, min, or max on a quantitative axis:
{
"type": "statistic",
"axis": "value",
"statistic": {
"operation": "average",
"scope": "visible",
"basis": "categoryTotals"
},
"label": {
"content": ["text", "value"],
"text": "Average"
}
}scope decides which data responds to interactive filtering:
| Scope | Behavior |
|---|---|
visible | Recalculates when legend filtering changes the visible data |
all | Retains the statistic calculated from the complete authored data |
Categorical statistics also accept basis:
| Basis | Behavior |
|---|---|
values | Treats every category and series value separately |
categoryTotals | Sums each category first, then calculates across those totals |
Omitting basis uses values. An optional series limits a categorical statistic to one authored series. Scatter statistics use the selected X or Y values and do not have category totals or a series selector.
Labels and formatting
Omit label to draw only the line. Label content is an ordered list containing text, value, or both without duplicates. Include text only with a nonempty text property.
{
"type": "statistic",
"axis": "value",
"statistic": {
"operation": "average",
"scope": "visible"
},
"label": {
"content": ["value", "text"],
"text": "Average"
}
}This produces a label such as 72.4 · Average. Calculated values remain accurate when a visible-scope statistic changes. Explicit axis formatting wins, followed by the reference's value-role formatting; automatic numeric formatting follows the chart locale.
Set label.width to a positive logical-pixel width to wrap the label. Omit it for automatic width. position places the label before or after the rule, or outside its start or end endpoint. align controls paragraph alignment inside the label box.
Domains and filtering
Visible references contribute to automatic continuous-axis domains by default. This keeps a target visible when filtering leaves only smaller values. Set contributeToDomain: false when the data alone should determine the automatic domain.
Explicit domains and normalized-share bounds always take precedence. A reference outside an explicit domain remains authored but is not drawn. Hidden references do not affect domains. Statistics are calculated before an eligible reference contributes its result to the domain; references never become observations or change aggregation.
Category references must identify a category already present in the authored domain. They do not add empty categories to the scale.
Appearance, layer, and space
stroke.style is solid, dashed, or dotted. stroke.width is a positive logical-pixel width, and stroke.color accepts the same scheme-aware colors as other authored paint.
Use layer: "back" to paint the rule behind chart geometry or layer: "front" to paint it in front. Omission resolves to front. The label remains part of the chart's label phase so it stays readable independently of the rule's layer.
Reference labels reserve layout space by default. Set reserveSpace: false for an intentional overlay, or choose horizontal and vertical reservation independently with an object.
Set visible: false to hide a reference without deleting it.
Edit references visually
In the web editor or Figma plugin, open Annotations and choose Add reference line. Select its axis and choose a fixed value or statistic. The inspector keeps calculation, label, position, line appearance, layer, and space adjustment as separate decisions.
In the web editor, drag a fixed reference line to update its value with a transient preview. Calculated references cannot be dragged because their value is owned by the selected statistic. Every accepted change participates in undo and redo.
An empty statistic produces a warning and is omitted from the current render. A non-finite result is an error. The authored reference remains available for repair rather than becoming a success-shaped fallback.
Visible data and category totals
The following chart compares a visible-scope average of category totals with an all-data average of individual values. Hide a series in the interactive chart to see only the visible-scope statistic change.
See Scales and axes for viewport behavior, Validation and Review for findings, and the Cookbook for every reference recipe.