Skip to main content

Region · Baseline · Marker

The three annotation primitives, with their full prop surface. All render as <Layers> children and share the interaction props (id, selected, selectable, hovered, editing, onChange) — those are documented once under Editing & creating; this page focuses on each primitive's geometry and labelling props. For the shared model (registers, depth, the indicator law) see The annotation model.

Baseline and Marker are near-duals — a horizontal line at a y, a vertical line at an x — and share most of their surface; Region is the shaded span.

Region​

A shaded span over an x range — a lap, a zone, a selected interval. Its label flies as a flag off the left edge.

src/examples/charts-annotation-region.tsx
import {
  ChartContainer,
  ChartRow,
  Layers,
  LineChart,
  Region,
  YAxis,
} from '@pond-ts/charts';
import { useSiteChartTheme } from '@site/src/theme/useSiteChartTheme';
import { singleHostSeries } from './lib/server-metrics';

const STEP_MS = 60_000;

/** A `<Region>` — a shaded x span with a flag label. Here it brackets a busy
 *  window on the cpu curve. */
export default function ChartsAnnotationRegion() {
  const theme = useSiteChartTheme();
  const series = singleHostSeries();
  const base = series.timeRange()!.begin();

  return (
    <ChartContainer range={series.timeRange()} width={560} theme={theme}>
      <ChartRow height={200}>
        <YAxis id="pct" side="right" format=".0%" />
        <Layers>
          <LineChart series={series} column="cpu" axis="pct" />
          <Region
            from={base + 40 * STEP_MS}
            to={base + 58 * STEP_MS}
            label="busy"
          />
        </Layers>
      </ChartRow>
    </ChartContainer>
  );
}
PropTypeDefaultPurpose
fromnumber—Start x in axis units (time or value).
tonumber—End x in axis units.
labelstring | falseautoChip label. Omit ⇒ auto-label from–to with the shared x formatter; false/'' ⇒ no chip.
edgesbooleantrueDraw the vertical side outlines at from/to. false ⇒ fill only (a soft highlight band).
onChange(next: { from: number; to: number }) => void—Editable: drag the body to move (both edges shift), drag an edge to resize.

Plus the shared interaction props (id, selected, selectable, hovered, editing).

Baseline​

A horizontal line at a y value, scaled against one row axis. Its label anchors at the line's height.

src/examples/charts-annotation-baseline.tsx
import {
  Baseline,
  ChartContainer,
  ChartRow,
  Layers,
  LineChart,
  YAxis,
} from '@pond-ts/charts';
import { useSiteChartTheme } from '@site/src/theme/useSiteChartTheme';
import { singleHostSeries } from './lib/server-metrics';

/** A `<Baseline>` — a horizontal line at a y value on a named axis. `indicator`
 *  also pins its value to the y-axis as an on-axis pill. */
export default function ChartsAnnotationBaseline() {
  const theme = useSiteChartTheme();
  const series = singleHostSeries();

  return (
    <ChartContainer range={series.timeRange()} width={560} theme={theme}>
      <ChartRow height={200}>
        <YAxis id="pct" side="right" format=".0%" />
        <Layers>
          <LineChart series={series} column="cpu" axis="pct" />
          <Baseline value={0.43} axis="pct" label="target" indicator />
        </Layers>
      </ChartRow>
    </ChartContainer>
  );
}
PropTypeDefaultPurpose
valuenumber—y value in the linked axis's units.
axisstringrow defaultWhich <YAxis> (by id) to measure against.
labelstring | falseautoChip label. Omit ⇒ format value with that axis's formatter; false/'' ⇒ no chip.
labelSide'left' | 'right''left'Which side the near-line label chip sits.
labelPosition'center' | 'above''center'center rides on the line; above sits just on top of it.
indicatorbooleanfalseAlso pin value to its y-axis as an on-axis pill.
onChange(value: number) => void—Editable: drag vertically to report a new value.

Plus the shared interaction props. Like Marker, the indicator pill shows the formatted value, never the label.

Marker​

A vertical line at an x position (a time, a distance, a lap boundary).

src/examples/charts-annotation-marker.tsx
import {
  ChartContainer,
  ChartRow,
  Layers,
  LineChart,
  Marker,
  YAxis,
} from '@pond-ts/charts';
import { useSiteChartTheme } from '@site/src/theme/useSiteChartTheme';
import { singleHostSeries } from './lib/server-metrics';

const STEP_MS = 60_000;

/** A `<Marker>` — a vertical line at an x. `indicator` also pins its time to
 *  the x-axis as an on-axis pill (the axis-edge counterpart of the chip). */
export default function ChartsAnnotationMarker() {
  const theme = useSiteChartTheme();
  const series = singleHostSeries();
  const base = series.timeRange()!.begin();

  return (
    <ChartContainer range={series.timeRange()} width={560} theme={theme}>
      <ChartRow height={200}>
        <YAxis id="pct" side="right" format=".0%" />
        <Layers>
          <LineChart series={series} column="cpu" axis="pct" />
          <Marker at={base + 40 * STEP_MS} label="deploy" indicator />
        </Layers>
      </ChartRow>
    </ChartContainer>
  );
}
PropTypeDefaultPurpose
atnumber—x position in axis units — epoch ms on a time axis, the value on a value axis.
labelstring | falseautoChip label. Omit ⇒ auto-label with the shared x formatter; false/'' ⇒ no chip.
indicatorbooleanfalseAlso pin at to the x-axis as an on-axis pill (the axis-edge counterpart of the chip).
onChange(at: number) => void—Editable: drag the line to report a new at (controlled — wire it back).

Plus the shared interaction props. Note the indicator law: the indicator pill always shows the formatted at, never the custom label (which stays the near-line chip).

Auto-labels and suppression​

All three share the same label convention:

  • Omit label → an automatic label from the shared axis formatter (a region shows from–to, a marker its at, a baseline its value).
  • label="text" → your text on the near-line chip.
  • label={false} (or '') → no chip at all — for an inert background band or context line where the raw axis value would be noise.

See also​