> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference lines

export const GraphEmbed = ({src, story, aspectRatio, borderRadius = '14px', args}) => {
  const STORYBOOK_BASE_URL = window.location.hostname === 'localhost' ? 'http://localhost:6006' : 'https://storybook-sdk.vercel.app';
  function buildArgsString(args) {
    if (!args) return '';
    const encodeValue = value => {
      if (value === null) return '!null';
      if (value === undefined) return '!undefined';
      if (typeof value === 'boolean') return `!${value}`;
      if (typeof value === 'number') return String(value);
      return encodeURIComponent(String(value));
    };
    const properties = Object.entries(args).map(([key, value]) => `${key}:${encodeValue(value)}`).join(';');
    return `&args=${properties}`;
  }
  const resolvedSrc = story ? `${STORYBOOK_BASE_URL}/iframe.html?id=${story}&viewMode=story&embed=1${buildArgsString(args)}` : src;
  const resolvedAspectRatio = aspectRatio ?? (story ? '16 / 9' : '10 / 6');
  return <iframe src={resolvedSrc} loading="lazy" allowfullscreen="true" style={{
    width: '100%',
    aspectRatio: resolvedAspectRatio,
    border: 'none',
    borderRadius,
    colorScheme: 'light'
  }} />;
};

A reference line marks a constant value — a sales target, a capacity ceiling, a zero baseline — that the rest of the chart is read against. It's a geom like any other: `geom.rule()`, layered into the spec with its own value and style.

## A horizontal goal line

Bind the rule to a constant `y` with `aes: { y: { value } }`. The `{ value }` form is a [constant mapping](/sdk-next/concepts/mappings#variables-and-constants) — it pins the aesthetic to a literal instead of a column:

<GraphEmbed story="features-reference-lines--horizontal-goal-line" />

```tsx theme={null}
import { useMemo } from 'react';
import { createSpec, pipe, geom, scale } from '@graphysdk/viz-engine';
import { GraphProvider, GraphRenderer } from '@graphysdk/react-renderer';

const data = {
  columns: [{ key: 'month' }, { key: 'revenue' }],
  rows: [
    { month: 'Jan', revenue: 1200 },
    { month: 'Feb', revenue: 1800 },
    { month: 'Mar', revenue: 2400 },
    { month: 'Apr', revenue: 1600 },
    { month: 'May', revenue: 3200 },
    { month: 'Jun', revenue: 2800 },
  ],
};

export function RevenueWithTarget() {
  const spec = useMemo(
    () =>
      pipe(
        createSpec({ x: 'month', y: 'revenue' }),
        geom.bar(),
        geom.rule({
          aes: { y: { value: 2500 } },
          params: { label: 'Target', lineType: 'dashed' },
        }),
        scale.x(),
        scale.y()
      ),
    []
  );

  return (
    <GraphProvider input={spec} data={data}>
      <GraphRenderer />
    </GraphProvider>
  );
}
```

The rule value participates in the y-scale's auto-domain — set a target above the tallest bar and the axis grows to fit it, so the line is never clipped off the top.

## Styling the line

Style the rule through its `params`:

<ParamField path="label" type="string">
  Optional inline text drawn alongside the line. Omit to draw a bare line.
</ParamField>

<ParamField path="labelPosition" type="'start' | 'end'" default="start">
  Anchors the label at the start or end of the line.
</ParamField>

<ParamField path="color" type="string">
  Stroke color. Falls back to the theme's reference-line token when unset.
</ParamField>

<ParamField path="strokeWidth" type="number" default="1">
  Line thickness in pixels.
</ParamField>

<ParamField path="lineType" type="'solid' | 'dashed' | 'dotted'" default="solid">
  Stroke style.
</ParamField>

## Vertical lines

Mark a constant along the x-axis with `aes: { x: { value } }` instead:

<GraphEmbed story="features-reference-lines--vertical-threshold" />

```tsx theme={null}
geom.rule({ aes: { x: { value: 40 } }, params: { label: 'Threshold' } });
```

<Note>
  A vertical rule requires a **numeric** x-axis — it marks a constant x-value,
  which only has meaning when x is continuous. Categorical and date x-axes
  support horizontal rules only.
</Note>

## Multiple rules

Rules compose like any other layer, and paint in spec order — a rule added after `geom.bar()` draws in front of the bars. Stack as many as you need:

<GraphEmbed story="features-reference-lines--multiple-rules" />

```tsx theme={null}
pipe(
  createSpec({ x: 'month', y: 'revenue' }),
  geom.bar(),
  geom.rule({
    aes: { y: { value: 1000 } },
    params: { label: 'Floor', lineType: 'dotted' },
  }),
  geom.rule({ aes: { y: { value: 2500 } }, params: { label: 'Target' } }),
  geom.rule({
    aes: { y: { value: 3500 } },
    params: { label: 'Ceiling', lineType: 'dotted' },
  }),
  scale.x(),
  scale.y()
);
```

## Flipped and secondary axes

A rule tracks the data space, not the screen. Under [`coord.flip()`](/sdk-next/concepts/coordinate-systems) a `{ y: { value } }` rule still marks a constant y — the renderer paints it as a vertical line because the y-axis now runs horizontally. To pin a rule to a [secondary axis](/sdk-next/graph-types/combo), add `yScaleType: 'secondary'`:

```tsx theme={null}
geom.rule({
  aes: { y: { value: 7 } },
  yScaleType: 'secondary',
  params: { label: 'SLA' },
});
```

## Related

* [Mappings & aesthetics](/sdk-next/concepts/mappings#variables-and-constants) — the `{ value }` constant form
* [Scales](/sdk-next/concepts/scales) — how the rule value extends the auto-domain
* [Coordinate systems](/sdk-next/concepts/coordinate-systems) — rules under `coord.flip()`