Charts - Reference Lines & Bands
Overlay fixed value markers and shaded regions on cartesian charts to highlight thresholds, targets, and ranges.
#Usage
import { ChartReferenceBand, ChartReferenceLine, ChartSvg } from '@primeui/vue-chart';<ChartSvg>
<!-- series and axes -->
<ChartReferenceLine :y="threshold" />
<ChartReferenceBand :y1="lower" :y2="upper" />
</ChartSvg>Reference lines and bands overlay fixed markers on cartesian charts. ChartReferenceLine draws a horizontal or vertical line at a fixed value; ChartReferenceBand shades a value range. Both support label, stroke, and dash styling.
#Reference Line
Add ChartReferenceLine to draw a horizontal or vertical line at a fixed value. Set y for a horizontal threshold line. Set x for a vertical line at a category or timestamp. Set both x and y to draw intersecting lines through a specific data point.
#Reference Band
Add ChartReferenceBand to shade a region between two values. Set y1 and y2 for a horizontal band. Set x1 and x2 for a vertical band spanning a time or category range.
#Label
Set label on either component to display text alongside the line or band. Set labelPosition to control placement: start, center, or end along the line direction. Labels default to end.
#Styling
Set stroke, lineStrokeWidth, and strokeDasharray to customize reference line appearance. Use strokeDasharray for dashed patterns: [6, 4] draws 6px dashes with 4px gaps. Set fill to an opaque color and fillOpacity to control the shaded region transparency. fillOpacity is the only opacity control and applies on top of the fill color.
#Multiple Axes
On multi-axis charts, set yAxisId to pin a reference line or band to a specific Y axis. Without yAxisId the primary Y axis is used. xAxisId is not needed because X axis reference lines always use the shared category axis.
#API
#ChartReferenceLine
| Prop | Type | Default | Description |
|---|---|---|---|
x | string | number | - | Horizontal position. Category string, timestamp, or numeric value. Draws a vertical line at this X position |
y | string | number | - | Vertical position. Numeric value on a value Y axis, or a category string on a band (category) Y axis. Draws a horizontal line at this Y value |
yAxisId | string | primary | Y axis to use for y positioning. Only needed on multi-axis charts |
label | string | - | Label text displayed alongside the line |
labelPosition | 'start' | 'center' | 'end' | 'end' | Placement of the label along the line |
labelColor | string | stroke color or theme | Label text color. Defaults to the stroke color when explicitly set, otherwise follows the theme text color |
labelFontSize | number | 11 | Label font size in pixels |
labelFontWeight | 'normal' | 'bold' | number | 500 | Label font weight |
labelBackground | string | - | Background fill color behind the label. Renders a rounded pill when set |
labelBackgroundOpacity | number | 1 | Opacity of the label background fill (0–1) |
labelPadding | number | 5 | Padding in pixels between label text and background edges |
labelBorderRadius | number | 4 | Corner radius for the label background pill |
stroke | string | #94a3b8 | Line color |
lineStrokeWidth | number | 1 | Line stroke width in pixels |
strokeDasharray | number[] | - | Dash pattern, e.g. [6, 4] for 6px dashes with 4px gaps |
placement | 'beforeData' | 'afterData' | 'afterData' | Z-order relative to data series. afterData renders the line on top of all series, beforeData renders it behind |
render | (context) => unknown | - | Custom line renderer. Replaces the default line entirely. SVG: return a VNode. Canvas: draw to ctx and return null |
#ChartReferenceBand
| Prop | Type | Default | Description |
|---|---|---|---|
x1 | string | number | - | Band start on the X axis. Category string, timestamp, or numeric value |
x2 | string | number | - | Band end on the X axis |
y1 | string | number | - | Band start on the Y axis. Numeric value on a value Y axis, or a category string on a band (category) Y axis |
y2 | string | number | - | Band end on the Y axis. Numeric value on a value Y axis, or a category string on a band (category) Y axis |
yAxisId | string | primary | Y axis to use for y1/y2 positioning. Only needed on multi-axis charts |
label | string | - | Label text displayed inside the band |
labelPosition | 'start' | 'center' | 'end' | 'center' | Placement of the label along the band |
labelColor | string | theme | Label text color |
labelFontSize | number | 11 | Label font size in pixels |
labelFontWeight | 'normal' | 'bold' | number | 500 | Label font weight |
fill | string | { color: string; opacity?: number } | '#0000001a' | Band fill color. Pass a string (use fillOpacity for transparency) or an object { color, opacity } |
fillOpacity | 0–1 | 1 | Band fill opacity |
stroke | string | - | Border stroke color drawn around the band rectangle |
placement | 'beforeData' | 'afterData' | 'beforeData' | Z-order relative to data series. beforeData renders the band behind all series, afterData renders it on top |