# Reference Area

> Shaded Y band for target ranges and thresholds on cartesian charts, with a solid or pattern fill, dashed edges, and Y-axis tick coloring

Source: https://ui.cortexcn.dev/docs/utility/reference-area

## Installation

```bash
npx shadcn@latest add @cortexcn/reference-area
```

## Usage

`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.

```tsx
import {
  LineChart,
  Line,
  Grid,
  ReferenceArea,
  ChartTooltip,
  XAxis,
} from "@/components/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`](https://ui.cortexcn.dev/docs/utility/background) (`diagonal`, `dots`, `cross`, …).

## Examples

### Dashed band with markers

### Pattern fill with axis labels

### Colored markers

## Gallery

See **Reference Band** examples on each cartesian chart gallery: [line](https://ui.cortexcn.dev/charts/line-chart), [area](https://ui.cortexcn.dev/charts/area-chart), [bar](https://ui.cortexcn.dev/charts/bar-chart), [composed](https://ui.cortexcn.dev/charts/composed-chart), [scatter](https://ui.cortexcn.dev/charts/scatter-chart), [candlestick](https://ui.cortexcn.dev/charts/candlestick-chart), [live line](https://ui.cortexcn.dev/charts/live-line-chart), and [profit/loss line](https://ui.cortexcn.dev/charts/profit-loss-line).