Charts

Data Visualisation Library

Compose Observable Plot powered charts using declarative React primitives. Combine multiple series, dual axes, interactive regions, and tooltips while keeping a predictable registration model.

Chart Types

Start with the chart primitives and layer on shared foundations to create full visual analytics experiences.

Line Charts

Plot continuous series with support for multiple axes, gradients, and annotations.

"use client";

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 ChartLineDemo() {
  // Get 24-hour sample with 5-minute intervals
  const data = getStandardSample();
  const formatTimeTick = getTimeTickFormatter();

  return (
    <Chart.Root data={data as unknown as ChartDataPoint[]} height={300}>
      <Chart.LineSeries
        x="timestamp"
        y="return_temp"
        name="Return Temperature"
        color="var(--primitives-color-dataviz-series-2)"
        currentValueDot
      />
      <Chart.LineSeries
        x="timestamp"
        y="outdoor_temp"
        name="Outdoor Temperature"
        color="var(--ambient-data-series-7)"
        currentValueDot={{
          size: 12,
          fill: "white",
          stroke: "var(--primitives-color-dataviz-series-7)",
          strokeWidth: 2.5,
        }}
      />
      <Chart.XAxis label="Time" tickFormat={formatTimeTick} />
      <Chart.YAxis label="Temperature (°F)" />
      <Chart.Legend />
    </Chart.Root>
  );
}

Explore Line Charts

Bar Charts

Compare discrete values over time or categories with stacked brushes and responsive spacing.

"use client";

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

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

export function ChartBarDemo() {
  // Get 24-hour sample and aggregate by hour for bar chart
  const sampleData = getStandardSample();
  const hourlyData = aggregateByHour(sampleData);
  const formatTimeTick = getTimeTickFormatter();

  return (
    <Chart.Root data={hourlyData as unknown as ChartDataPoint[]} height={300}>
      <Chart.BarSeries
        x="timestamp"
        y="avg_supply_temp"
        name="Avg Supply Temperature"
        color="var(--primitives-color-dataviz-series-5)"
        interval="hour"
      />
      <Chart.XAxis label="Time" tickFormat={formatTimeTick} />
      <Chart.YAxis label="Temperature (°F)" />
      <Chart.Legend />
    </Chart.Root>
  );
}

Explore Bar Charts

Gauge Charts

Visualise proportions across operating states or categories with horizontal segmented bars.

HVAC Time States (24h)

Time in Temperature Zones (24h)

System Utilization (%)

Energy Consumption Breakdown

Comfort Zone Distribution

"use client";

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

import {
  getComfortZones,
  getEnergyBreakdown,
  getHVACTimeStates,
  getSystemUtilization,
  getTemperatureZones,
} from "./data/gauge-data";

export function ChartGaugeDemo() {
  // Get sample data
  const hvacStates = getHVACTimeStates();
  const tempZones = getTemperatureZones();
  const systemUtil = getSystemUtilization();
  const energyData = getEnergyBreakdown();
  const comfortData = getComfortZones();

  return (
    <div className="w-full space-y-8">
      {/* HVAC Time States */}
      <div>
        <h3 className="mb-2 text-sm font-medium">HVAC Time States (24h)</h3>
        <Chart.Root marginTop={0} marginBottom={0}>
          <Chart.GaugeSeries
            data={hvacStates as unknown as ChartDataPoint[]}
            category="category"
            value="value"
            colors={[
              "var(--primitives-color-dataviz-series-1-area)", // Heating
              "var(--primitives-color-dataviz-series-3-area)", // Cooling
              "var(--primitives-color-dataviz-series-5-area)", // Idle
            ]}
            height={20}
          />
        </Chart.Root>
      </div>

      {/* Temperature Zones */}
      <div>
        <h3 className="mb-2 text-sm font-medium">
          Time in Temperature Zones (24h)
        </h3>
        <Chart.Root marginTop={0} marginBottom={0}>
          <Chart.GaugeSeries
            data={tempZones as unknown as ChartDataPoint[]}
            category="category"
            value="value"
            colors={[
              "var(--primitives-color-dataviz-series-6-area)", // Below
              "var(--primitives-color-dataviz-series-4-area)", // At
              "var(--primitives-color-dataviz-series-2-area)", // Above
            ]}
            height={20}
          />
        </Chart.Root>
      </div>

      {/* System Utilization */}
      <div>
        <h3 className="mb-2 text-sm font-medium">System Utilization (%)</h3>
        <Chart.Root marginTop={0} marginBottom={0}>
          <Chart.GaugeSeries
            data={systemUtil as unknown as ChartDataPoint[]}
            category="category"
            value="value"
            colors={[
              "var(--primitives-color-dataviz-series-4-area)", // Active
              "var(--primitives-color-dataviz-series-7-area)", // Standby
              "var(--primitives-color-dataviz-series-5-area)", // Off
            ]}
            height={20}
          />
        </Chart.Root>
      </div>

      {/* Energy Breakdown */}
      <div>
        <h3 className="mb-2 text-sm font-medium">
          Energy Consumption Breakdown
        </h3>
        <Chart.Root marginTop={0} marginBottom={0}>
          <Chart.GaugeSeries
            data={energyData as unknown as ChartDataPoint[]}
            category="category"
            value="value"
            height={20}
          />
        </Chart.Root>
      </div>

      {/* Comfort Zones */}
      <div>
        <h3 className="mb-2 text-sm font-medium">Comfort Zone Distribution</h3>
        <Chart.Root marginTop={0} marginBottom={0}>
          <Chart.GaugeSeries
            data={comfortData as unknown as ChartDataPoint[]}
            category="category"
            value="value"
            colors={[
              "var(--primitives-color-dataviz-series-3-area)", // Too Cold
              "var(--primitives-color-dataviz-series-4-area)", // Comfortable
              "var(--primitives-color-dataviz-series-1-area)", // Too Warm
            ]}
            height={20}
          />
        </Chart.Root>
      </div>
    </div>
  );
}

Explore Gauge Charts

Foundations

Cross-cutting features attach to any chart type and share the same tooltip, interaction, and styling primitives.

Tooltip

Shared tooltip and crosshair logic providing formatted values, annotation callouts, and responsive positioning.

"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>
  );
}

Learn about tooltip

Regions

Highlight time or value bands to call attention to operational windows, forecast ranges, or alerts.

"use client";

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 ChartRegionsDemo() {
  // Get 24-hour sample with 5-minute intervals
  const data = getStandardSample();
  const formatTimeTick = getTimeTickFormatter();

  // Find cooling cycle periods (where cycle_mode === "Cool")
  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;
    }
  });

  // Close last period if still in cooling at end
  if (cycleStart !== null) {
    coolingPeriods.push({
      start: cycleStart,
      end: data[data.length - 1].timestamp,
    });
  }

  return (
    <Chart.Root data={data as unknown as ChartDataPoint[]} height={300}>
      {/* Time period regions for cooling cycles */}
      {coolingPeriods.map((period, index) => (
        <Chart.Region
          key={index}
          type="time"
          start={period.start}
          end={period.end}
          color="var(--primitives-color-dataviz-series-6)"
          opacity={0.1}
        />
      ))}

      {/* Value range region for operational envelope (72-78°F) */}
      <Chart.Region
        type="value"
        start={72}
        end={78}
        color="var(--primitives-color-dataviz-series-3)"
        opacity={0.1}
      />

      <Chart.LineSeries
        x="timestamp"
        y="supply_temp"
        name="Supply Temp"
        color="var(--primitives-color-dataviz-series-5)"
      />
      <Chart.LineSeries
        x="timestamp"
        y="return_temp"
        name="Return Temp"
        color="var(--primitives-color-dataviz-series-2)"
      />
      <Chart.XAxis label="Time" tickFormat={formatTimeTick} ticks={6} />
      <Chart.YAxis label="Temperature (°F)" />
      <Chart.Legend />
    </Chart.Root>
  );
}

Learn about regions

Annotations

Reference lines and labels that keep operators aligned on thresholds, set points, and projections.

"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>
  );
}

Learn about annotations

Brushing

Interactive zooming with deterministic callbacks so parent pages can sync filtered views.

"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>
  );
}

Learn about brushing

Full Feature Demo

The interactive example combines multiple series, dual axes, regions, annotations, and brushing. Use it as a baseline when validating new changes to the chart runtime.

"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>
  );
}