Foundations

Annotations

Call out thresholds, forecasts, or special events. Annotations augment tooltips, legends, and the visual layer without interfering with series registration.

Example

"use client";

import { useMemo } from "react";

import * as Chart from "@smartacteam/ambient-web/chart";
import { ChartDataPoint } from "@smartacteam/ambient-web/chart";

import { getFilterPerformanceData } from "./data/filter-performance-data";

const formatDateTick = (() => {
  const formatter = new Intl.DateTimeFormat("en-US", {
    month: "short",
    day: "numeric",
  });
  return (value: number | Date | string) => {
    const date = value instanceof Date ? value : new Date(String(value));
    return formatter.format(date);
  };
})();

export function ChartAnnotationsDemo() {
  const data = useMemo(() => getFilterPerformanceData(), []);
  const changePoint = useMemo(() => {
    for (let i = 1; i < data.length; i += 1) {
      const previous = data[i - 1];
      const current = data[i];
      if (current.efficiency >= 100 && previous.efficiency < 95) {
        return current;
      }
    }
    return data.find((point) => point.efficiency >= 100);
  }, [data]);

  return (
    <Chart.Root data={data as unknown as ChartDataPoint[]} height={300}>
      <Chart.LineSeries
        x="timestamp"
        y="efficiency"
        name="Filter Efficiency"
        color="var(--primitives-color-dataviz-series-5)"
        strokeWidth={3}
      />

      <Chart.Annotation
        type="line"
        y={90}
        label="Optimal Range"
        color="var(--primitives-color-dataviz-series-1)"
        strokeDasharray="6,4"
      />

      {changePoint && (
        <Chart.Annotation
          type="line"
          x={changePoint.timestamp}
          label="Filter change detected"
          color="var(--primitives-color-dataviz-series-7)"
          strokeWidth={2}
          labelMarkOptions={{
            frameAnchor: "bottom",
            dy: -10,
          }}
        />
      )}

      <Chart.XAxis label="Date" tickFormat={formatDateTick} ticks={6} />
      <Chart.YAxis label="Efficiency (%)" domain={[60, 102]} />
      <Chart.Legend />
    </Chart.Root>
  );
}

The sample chart combines horizontal line annotations for temperature targets with labels that reflow to avoid overlapping the data.

Usage

<Chart.Annotation
  type="line"
  y={75}
  label="Supply target"
  color="var(--ambient-data-series-5)"
  strokeDasharray="4,4"
/>
<Chart.Annotation
  type="line"
  y={82}
  label="Return threshold"
/>
<Chart.Annotation
  type="line"
  x={changeTimestamp}
  label="Filter change detected"
  labelMarkOptions={{ frameAnchor: "bottom", dy: -10 }}
/>

Props

Chart.Annotation
Prop	Type	Default	Description
type	`"line" \| "x-band" \| "y-band" \| "point"`	—	Select the annotation primitive. Horizontal `line` annotations use `y`, vertical use `x`.
x	DomainInput	—	X-position for vertical lines or points. Accepts Date or numeric values.
y	number	—	Y-position for horizontal lines or points. Uses the same units as the axis domain.
label	string	—	Optional text label rendered near the annotation. Fine-tune placement through `labelMarkOptions`.
color	string	Theme annotation token	Stroke colour and tooltip accent for the annotation. Use theme variables where possible.
axis	string	`"y"`	Bind to a secondary axis so transformed values align correctly with dual-axis charts.
strokeWidth	number	1	Line weight for the annotation stroke.
strokeDasharray	string	—	Pattern for dashed annotations (`"4,2"`). Helpful for forecast markers.
labelMarkOptions	`Partial<Plot.TextOptions>`	—	Advanced text mark configuration forwarded to Observable Plot. Control `textAnchor`, `lineAnchor`, `frameAnchor`, `dx`, `dy`, `rotate`, and more.

Recommendations

Use high-contrast colours so annotations remain legible.
Keep labels short; the tooltip already surfaces full annotation details.
Align annotation axes with the series they describe to avoid confusion when using secondary scales.