# ReferenceLine

A horizontal or vertical reference line to mark important values on a chart, such as targets, thresholds, or baseline values.

## Import

```tsx
import { ReferenceLine } from '@coinbase/cds-mobile-visualization'
```

## Examples

### Basics

ReferenceLine can be used to add important details to a chart, such as a reference price or date. You can create horizontal lines using `dataY` or vertical lines using `dataX`.

#### Simple Reference Line

A minimal reference line without labels, useful for marking key thresholds:

```jsx
function SimpleReferenceLineExample() {
  const theme = useTheme();

  return (
    <LineChart
      showArea
      height={150}
      series={[
        {
          id: 'prices',
          data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
          color: theme.color.fgPositive,
        },
      ]}
    >
      <ReferenceLine
        LineComponent={(props) => <DottedLine {...props} dashIntervals={[0, 16]} strokeWidth={3} />}
        dataY={10}
        stroke={theme.color.fg}
      />
    </LineChart>
  );
}
```

#### With Labels

You can add text labels to reference lines and position them using alignment and offset props:

```jsx
function WithLabelsExample() {
  return (
    <LineChart
      height={150}
      series={[
        {
          id: 'prices',
          data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
        },
      ]}
      inset={0}
      showArea
    >
      <ReferenceLine
        dataX={5}
        label="Vertical Reference Line"
        labelDx={8}
        labelHorizontalAlignment="left"
      />
      <ReferenceLine
        dataY={50}
        label="Horizontal Reference Line"
        labelDy={-8}
        labelHorizontalAlignment="right"
        labelVerticalAlignment="bottom"
      />
    </LineChart>
  );
}
```

### Data Values

ReferenceLine relies on `dataX` or `dataY` to position the line. Passing in `dataY` will create a horizontal line across the y axis at that value, and passing in `dataX` will do the same along the x axis.

```jsx
function DataValuesExample() {
  const theme = useTheme();

  return (
    <LineChart
      showArea
      curve="natural"
      height={150}
      series={[
        {
          id: 'growth',
          data: [
            2, 4, 8, 15, 30, 65, 140, 280, 580, 1200, 2400, 4800, 9500, 19000, 38000, 75000, 150000,
          ],
          color: theme.color.fgPositive,
        },
      ]}
    >
      <ReferenceLine
        dataY={10000}
        label="10,000"
        labelDy={-4}
        labelPosition="left"
        labelVerticalAlignment="bottom"
      />
      <ReferenceLine
        dataY={100000}
        label="100,000"
        labelDy={-4}
        labelPosition="left"
        labelVerticalAlignment="bottom"
      />
    </LineChart>
  );
}
```

### Labels

#### Customization

You can customize label appearance using `labelFont`, `labelDx`, `labelDy`, `labelHorizontalAlignment`, and `labelVerticalAlignment` props.

```jsx
function LabelCustomizationExample() {
  return (
    <LineChart
      height={150}
      series={[
        {
          id: 'prices',
          data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
        },
      ]}
      showArea
    >
      <ReferenceLine
        dataY={50}
        label="Target Price"
        labelDy={-8}
        labelFont="legal"
        labelHorizontalAlignment="right"
        labelPosition="right"
        labelVerticalAlignment="bottom"
      />
      <ReferenceLine
        dataX={7}
        label="Midpoint"
        labelDx={8}
        labelFont="label1"
        labelHorizontalAlignment="left"
        labelPosition="top"
      />
    </LineChart>
  );
}
```

#### Bounds

Use `labelBoundsInset` to prevent labels from getting too close to chart edges.

```jsx
function BoundsExample() {
  return (
    <LineChart
      height={150}
      inset={{ left: 0, right: 0 }}
      series={[
        {
          id: 'prices',
          data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
        },
      ]}
      showArea
    >
      <ReferenceLine
        dataX={0}
        label="No Bounds Inset"
        labelBoundsInset={0}
        labelDy={0}
        labelPosition="top"
      />
      <ReferenceLine
        dataX={13}
        label="12px Bounds Inset"
        labelBoundsInset={{ left: 12, right: 12 }}
        labelDy={0}
        labelPosition="top"
      />
    </LineChart>
  );
}
```

#### Custom Component

You can adjust the style of the label using a custom `LabelComponent`.

```jsx
function LabelStyleExample() {
  const theme = useTheme();

  const LiquidationLabel = useMemo(
    () =>
      memo((props) => (
        <DefaultReferenceLineLabel
          {...props}
          background={theme.color.accentSubtleYellow}
          borderRadius={4}
          color={`rgb(${theme.color.accentSubtleYellow})`}
          dx={12}
          font="label1"
          horizontalAlignment="left"
          inset={{ top: 4, bottom: 4, left: 8, right: 8 }}
        />
      )),
    [theme.color.accentSubtleYellow],
  );

  const PriceLabel = useMemo(
    () =>
      memo((props) => (
        <DefaultReferenceLineLabel
          {...props}
          background={theme.color.bg}
          borderRadius={4}
          color={`rgb(${theme.color.yellow70})`}
          dx={-12}
          font="label1"
          horizontalAlignment="right"
          inset={{ top: 2, bottom: 2, left: 4, right: 4 }}
        />
      )),
    [theme.color.bg, theme.color.yellow70],
  );

  return (
    <LineChart
      height={150}
      inset={{ right: 4 }}
      series={[
        {
          id: 'prices',
          data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
        },
      ]}
    >
      <ReferenceLine
        LabelComponent={LiquidationLabel}
        dataY={25}
        label="Liquidation"
        labelPosition="left"
        stroke={theme.color.bgWarning}
      />
      <ReferenceLine
        LabelComponent={PriceLabel}
        dataY={25}
        label="$25"
        labelPosition="right"
        stroke="transparent"
      />
    </LineChart>
  );
}
```

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `LabelComponent` | `ReferenceLineLabelComponent` | No | `DefaultReferenceLineLabel` | Component to render the label. |
| `LineComponent` | `LineComponent` | No | `DottedLine` | Component to render the line. |
| `dataX` | `number \| { value: number; }` | No | `-` | X-value for vertical reference line (data index). |
| `dataY` | `number \| { value: number; }` | No | `-` | Y-value for horizontal reference line (data value). |
| `label` | `string \| SkParagraph \| { value: string \| SkParagraph; }` | No | `-` | Label content to display near the reference line. Can be a string or ReactNode for rich formatting. |
| `labelBoundsInset` | `number \| ChartInset` | No | `{ top: 4, bottom: 20, left: 12, right: 12 } when labelElevated is true, otherwise none` | Bounds inset for the label to prevent cutoff at chart edges. Especially useful when labelElevated is true to prevent shadow clipping. Can be a number (applied to all sides) or a ChartInset object. |
| `labelDx` | `number` | No | `-` | Horizontal offset for the label in pixels. |
| `labelDy` | `number` | No | `-` | Vertical offset for the label in pixels. |
| `labelElevated` | `boolean` | No | `-` | Whether to elevate the label with a shadow. When true, applies elevation and automatically adds bounds to keep label within chart area. |
| `labelFont` | `display1 \| display2 \| display3 \| title1 \| title2 \| title3 \| title4 \| headline \| body \| label1 \| label2 \| caption \| legal` | No | `-` | Font style for the label text. |
| `labelHorizontalAlignment` | `left \| right \| center` | No | `-` | Horizontal alignment of the label text. |
| `labelPosition` | `TextHorizontalAlignment \| TextVerticalAlignment` | No | `'right' 'top'` | Position of the label along the horizontal line. Position of the label along the vertical line. |
| `labelVerticalAlignment` | `top \| bottom \| middle` | No | `-` | Vertical alignment of the label text. |
| `opacity` | `number \| { value: number; }` | No | `1` | Opacity applied to both the line and label. |
| `stroke` | `string` | No | `theme.color.bgLine` | The color of the line. |
| `yAxisId` | `string` | No | `-` | The ID of the y-axis to use for positioning. Defaults to defaultAxisId if not specified. |


