Reference lines

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 — it pins the aesthetic to a literal instead of a column:

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:

label

string

Optional inline text drawn alongside the line. Omit to draw a bare line.

labelPosition

'start' | 'end'

default:"start"

Anchors the label at the start or end of the line.

color

string

Stroke color. Falls back to the theme’s reference-line token when unset.

strokeWidth

number

default:"1"

Line thickness in pixels.

lineType

'solid' | 'dashed' | 'dotted'

default:"solid"

Stroke style.

Vertical lines

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

geom.rule({ aes: { x: { value: 40 } }, params: { label: 'Threshold' } });

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.

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:

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() 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, add yScaleType: 'secondary':

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

Mappings & aesthetics — the { value } constant form
Scales — how the rule value extends the auto-domain
Coordinate systems — rules under coord.flip()

Get Started

Core concepts

Chart types

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

A horizontal goal line

Styling the line

Vertical lines

Multiple rules

Flipped and secondary axes

​A horizontal goal line

​Styling the line

​Vertical lines

​Multiple rules

​Flipped and secondary axes

​Related

A horizontal goal line

Styling the line

Vertical lines

Multiple rules

Flipped and secondary axes

Related