Reference Area | Bklit UI

Preview

Installation

pnpm dlx shadcn@latest add @bklit/reference-area

pnpm dlx shadcn@latest add @bklit/reference-area

ReferenceArea draws a horizontal band between two Y data values. Place it as a child of any cartesian chart (LineChart, AreaChart, BarChart, ScatterChart, CandlestickChart, ComposedChart, LiveLineChart). It renders in the underlay layer — above grid and background, behind series.

import { LineChart, Line, Grid, ReferenceArea, ChartTooltip, XAxis } from "@bklitui/ui/charts";

<LineChart data={data}>
  <Grid horizontal />
  <ReferenceArea y1={160} y2={220} strokeStyle="dashed" showMarkers />
  <Line dataKey="value" />
  <XAxis />
  <ChartTooltip />
</LineChart>

Omit y1 or y2 to extend the band to the top or bottom of the plot. Use axisLabelColor to tint Y-axis tick labels whose values fall inside the band.

Props

Prop	Type	Default	Description
`y1`	`number`	—	Lower Y data bound (extends to plot top when omitted)
`y2`	`number`	—	Upper Y data bound (extends to plot bottom when omitted)
`x1`	`Date \| number`	—	Starting X data coordinate (extends to plot left when omitted)
`x2`	`Date \| number`	—	Ending X data coordinate (extends to plot right when omitted)
`yAxisId`	`string \| number`	`"left"`	Y-scale group id
`fill`	`string`	muted mix on `--chart-foreground-muted`	Solid fill when `pattern` is `"none"`
`fillOpacity`	`number`	`1`	Fill opacity
`pattern`	Pattern preset id	`"none"`	Pattern fill inside the band
`patternColor`	`string`	—	Pattern stroke or tile color
`patternScale`	`number`	—	Pattern tile scale
`patternStrokeWidth`	`number`	—	Line stroke width for line-based patterns
`patternRadius`	`number`	—	Dot or circle radius for `dots` / `circles`
`patternComplement`	`boolean`	—	Alternate tile fill for circle patterns
`patternFill`	`string`	—	Solid fill inside circles
`patternDotFill`	`boolean`	—	Dot grid only — hollow dots when `false`
`patternTileBackground`	`string`	—	Background color inside each pattern tile
`stroke`	`string`	—	Edge line color
`strokeWidth`	`number`	`1`	Edge line width
`strokeStyle`	`"solid" \| "dashed"`	`"solid"`	Edge line style
`strokeDasharray`	`string`	`"4,4"`	Dash array when `strokeStyle` is `"dashed"`
`fadeEdges`	`boolean`	`true`	Fade fill and edges at left/right
`fadeEdgesLength`	`number`	`10`	Horizontal fade zone as % of plot width per edge (0–45)
`axisLabelColor`	`string`	—	Y-axis tick label color for values inside the band
`showMarkers`	`boolean`	`false`	Inward bracket markers at the horizontal center
`markerColor`	`string`	—	Bracket marker color
`markerSize`	`number`	—	Bracket marker size
`ifOverflow`	`"hidden" \| "visible"`	`"hidden"`	Clip band to the plot when bounds exceed the domain

Pattern presets match Background (diagonal, dots, cross, …).

Studio

Edit in Studio

Open in Studio

Open Studio with the line chart and select Reference Area in the layers panel to tune bounds, fill, pattern, edges, and markers. The same layer is available on area, bar, candlestick, composed, live line, line, and scatter charts.

Examples

Dashed band with markers

<LineChart data={data}>
  <Grid horizontal />
  <ReferenceArea y1={160} y2={220} strokeStyle="dashed" showMarkers />
  <Line dataKey="value" />
  <XAxis />
  <ChartTooltip />
</LineChart>

<LineChart data={data}>  <Grid horizontal />  <ReferenceArea y1={160} y2={220} strokeStyle="dashed" showMarkers />  <Line dataKey="value" />  <XAxis />  <ChartTooltip /></LineChart>

Pattern fill with axis labels

<LineChart data={data}>
<Grid horizontal />
<ReferenceArea
  y1={160}
  y2={200}
  pattern="diagonal"
  patternColor="oklch(0.76 0.144 180.392 / 0.17)"
  patternScale={0.75}
  patternStrokeWidth={1.5}
  stroke="oklch(0.841 0.142 159.667 / 0.49)"
  axisLabelColor="oklch(0.795 0.152 164.722)"
/>
<Line dataKey="value" />
<XAxis />
<ChartTooltip />
</LineChart>

<LineChart data={data}><Grid horizontal /><ReferenceArea  y1={160}  y2={200}  pattern="diagonal"  patternColor="oklch(0.76 0.144 180.392 / 0.17)"  patternScale={0.75}  patternStrokeWidth={1.5}  stroke="oklch(0.841 0.142 159.667 / 0.49)"  axisLabelColor="oklch(0.795 0.152 164.722)"/><Line dataKey="value" /><XAxis /><ChartTooltip /></LineChart>

Colored markers

<LineChart data={data}>
<Grid horizontal />
<ReferenceArea
  y1={160}
  y2={220}
  stroke="var(--chart-1)"
  strokeStyle="dashed"
  showMarkers
  markerColor="var(--chart-1)"
/>
<Line dataKey="value" />
<XAxis />
<ChartTooltip />
</LineChart>

<LineChart data={data}><Grid horizontal /><ReferenceArea  y1={160}  y2={220}  stroke="var(--chart-1)"  strokeStyle="dashed"  showMarkers  markerColor="var(--chart-1)"/><Line dataKey="value" /><XAxis /><ChartTooltip /></LineChart>

Gallery

See Reference Band examples on each cartesian chart gallery: line, area, bar, composed, scatter, candlestick, live line, and profit/loss line.