Foundations

Tooltip & Crosshair

The tooltip presents aligned values across every registered series, keeps annotations in view, and manages the crosshair position. It lives inside `Chart.Root`, so any chart type automatically participates without extra configuration.

Example

"use client";

import { useState } from "react";

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

import { getStandardSample } from "./data/sample-data";
import { getTimeTickFormatter } from "./utils/chart-formatters";

export function ChartInteractiveDemo() {
  // Get 24-hour sample
  const data = getStandardSample();
  const formatTimeTick = getTimeTickFormatter();
  const domain: [Date, Date] = [
    new Date(Math.min(...data.map((d) => d.timestamp))),
    new Date(Math.max(...data.map((d) => d.timestamp))),
  ];
  const [brushDomain, setBrushDomain] = useState<[Date, Date] | null>(null);

  // Find cooling cycle periods
  const coolingPeriods: Array<{ start: number; end: number }> = [];
  let cycleStart: number | null = null;

  data.forEach((point, index) => {
    if (point.cycle_mode === "Cool" && cycleStart === null) {
      cycleStart = point.timestamp;
    } else if (point.cycle_mode !== "Cool" && cycleStart !== null) {
      coolingPeriods.push({
        start: cycleStart,
        end: data[index - 1].timestamp,
      });
      cycleStart = null;
    }
  });

  if (cycleStart !== null) {
    coolingPeriods.push({
      start: cycleStart,
      end: data[data.length - 1].timestamp,
    });
  }

  return (
    <div className="flex w-full flex-col gap-3 font-booton text-base">
      {brushDomain && (
        <div className="flex items-center justify-between text-base text-foreground-secondary">
          <span>
            Zoomed: {brushDomain[0].toLocaleTimeString()} -{" "}
            {brushDomain[1].toLocaleTimeString()}
          </span>
          <Button
            size="sm"
            variant="default"
            type="button"
            onClick={() => setBrushDomain(null)}
          >
            Reset zoom
          </Button>
        </div>
      )}
      <Chart.Root
        data={data as unknown as ChartDataPoint[]}
        height={400}
        marginRight={80}
        brush={true}
        onBrush={setBrushDomain}
      >
        {/* Axes first so dependent series scales exist */}
        <Chart.YAxis position="left" label="Temperature (°F)" />
        <Chart.YAxis position="right" name="pressure" label="Pressure (Pa)" />
        <Chart.XAxis
          label="Time"
          tickFormat={formatTimeTick}
          ticks={6}
          domain={brushDomain ?? domain}
          nice={false}
        />
        {/* Time period regions for cooling cycles */}
        {coolingPeriods.map((period, index) => (
          <Chart.Region
            key={`cooling-${index}`}
            type="time"
            start={period.start}
            end={period.end}
            color="var(--primitives-color-dataviz-series-6)"
            opacity={0.1}
          />
        ))}

        {/* Operational envelope */}
        <Chart.Region
          type="value"
          start={72}
          end={78}
          color="var(--primitives-color-dataviz-series-3)"
          opacity={0.08}
        />

        {/* Line series on primary axis using raw data */}
        <Chart.LineSeries
          data={data as unknown as ChartDataPoint[]}
          x="timestamp"
          y="supply_temp"
          name="Supply Temp"
          color="var(--primitives-color-dataviz-series-5)"
          strokeWidth={2}
        />
        <Chart.LineSeries
          data={data as unknown as ChartDataPoint[]}
          x="timestamp"
          y="return_temp"
          name="Return Temp"
          color="var(--primitives-color-dataviz-series-2)"
          strokeWidth={2}
        />
        <Chart.LineSeries
          data={data as unknown as ChartDataPoint[]}
          x="timestamp"
          y="outdoor_temp"
          name="Outdoor Temp"
          color="var(--primitives-color-dataviz-series-7)"
          strokeWidth={2}
        />

        {/* Line series on secondary axis using raw data */}
        <Chart.LineSeries
          data={data as unknown as ChartDataPoint[]}
          x="timestamp"
          y="return_pressure"
          name="Pressure"
          color="var(--primitives-color-dataviz-series-4)"
          strokeWidth={2}
          axis="pressure"
        />

        {/* Reference lines */}
        <Chart.Annotation
          type="line"
          y={75}
          label="Supply Target"
          color="var(--primitives-color-dataviz-series-5)"
        />
        <Chart.Annotation
          type="line"
          y={82}
          label="Return Target"
          color="var(--primitives-color-dataviz-series-2)"
        />

        {/* Legend */}
        <Chart.Legend />
      </Chart.Root>
    </div>
  );
}

Move your cursor across the chart. You'll see the shared tooltip aggregate line, bar, and gauge values while highlighting the active timestamp with a crosshair.

Usage

<Chart.Root data={data} tooltip>
  <Chart.LineSeries x="timestamp" y="supply_temp" name="Supply" unit="°F" />
  <Chart.LineSeries x="timestamp" y="return_temp" name="Return" unit="°F" />
  <Chart.Annotation type="line" y={75} label="Target" />
</Chart.Root>

Units and annotation labels enrich the tooltip without any custom render logic.

Configuration touchpoints

Prop	Type	Default	Description
tooltip	boolean	true	Root-level flag for enabling the shared tooltip, crosshair, and pointer tracking layer.
unit	string	—	Per-series option (Line/Bar/Gauge) that appends a suffix to formatted values inside the tooltip.
showPercentages	boolean	false	Gauge-specific prop that switches tooltip values from raw numbers to percentages.
annotations	Chart.Annotation[]	[]	Registered annotations show up in the tooltip when the pointer crosses their reference line.

Best practices

Provide `unit` strings on every series so the tooltip does not have to infer units from axis labels.
Return cleanup functions from registration hooks (already handled in the chart components) to prevent duplicate tooltip entries when toggling series.
Keep the tooltip enabled even for simple charts—it provides keyboard focus states and accessible descriptions for screen-reader users.