# 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

### Basic Example

ReferenceLine can be used to add important details to a chart, such as a reference price or date.

```jsx
<LineChart
  height={150}
  series={[
    {
      id: 'prices',
      data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
    },
  ]}
  inset={0}
  curve="monotone"
  showArea
>
  <ReferenceLine
    dataX={5}
    label="Vertical Reference Line"
    labelProps={{ horizontalAlignment: 'left', dx: 8 }}
  />
  <ReferenceLine
    dataY={50}
    label="Horizontal Reference Line"
    labelProps={{ verticalAlignment: 'bottom', dy: -8, horizontalAlignment: 'right' }}
  />
</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"
        labelPosition="left"
        labelProps={{ verticalAlignment: 'bottom', dy: -4 }}
      />
      <ReferenceLine
        dataY={100000}
        label="100,000"
        labelPosition="left"
        labelProps={{ verticalAlignment: 'bottom', dy: -4 }}
      />
    </LineChart>
  );
}
```

### Customization

#### Label Style

You can adjust the style of the label using the `labelProps` prop.

```jsx
function LabelStyleExample() {
  const theme = useTheme();
  return (
    <LineChart
      curve="monotone"
      height={150}
      inset={{ right: 4 }}
      series={[
        {
          id: 'prices',
          data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
        },
      ]}
    >
      <ReferenceLine
        dataY={25}
        label="Liquidation"
        labelPosition="left"
        labelProps={{
          horizontalAlignment: 'left',
          dx: 12,
          borderRadius: 4,
          inset: { top: 4, bottom: 4, left: 8, right: 8 },
          color: `rgb(${theme.color.accentSubtleYellow})`,
          background: theme.color.accentSubtleYellow,
          font: 'label1',
        }}
        stroke={theme.color.bgWarning}
      />
      <ReferenceLine
        dataY={25}
        label="$25"
        labelPosition="right"
        labelProps={{
          horizontalAlignment: 'right',
          dx: -12,
          borderRadius: 4,
          inset: { top: 2, bottom: 2, left: 4, right: 4 },
          color: `rgb(${theme.color.yellow70})`,
          background: theme.color.bg,
          font: 'label1',
        }}
        stroke="transparent"
      />
    </LineChart>
  );
}
```

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `LineComponent` | `LineComponent` | No | `DottedLine` | Component to render the line. |
| `dataX` | `number` | No | `-` | X-value for vertical reference line (data index). |
| `dataY` | `number` | No | `-` | Y-value for horizontal reference line (data value). |
| `label` | `null \| string \| number \| ReactElement<TSpanProps, TSpan> \| ReactElement<TextPathProps, TextPath> \| ValidChartTextChildElements[]` | No | `-` | Label content to display near the reference line. Can be a string or ReactNode for rich formatting. |
| `labelPosition` | `TextHorizontalAlignment \| TextVerticalAlignment` | No | `'right' 'top'` | Position of the label along the horizontal line. Position of the label along the vertical line. |
| `labelProps` | `ReferenceLineLabelProps` | No | `-` | Props for the label rendering. Consolidates styling and positioning options for the ChartText component. Alignment defaults are set based on line orientation and can be overridden here. |
| `stroke` | `string` | No | `theme.color.bgLine` | The color of the line. |
| `testID` | `string` | No | `-` | Used to locate this element in unit and end-to-end tests. Under the hood, testID translates to data-testid on Web. On Mobile, testID stays the same - testID |
| `yAxisId` | `string` | No | `-` | The ID of the y-axis to use for positioning. Defaults to defaultAxisId if not specified. |


