Foundations

Brushing & Zoom

Brushing lets users focus on a specific time range while keeping the full dataset intact. The callback provides the selected domain so you can sync filters elsewhere in the UI.

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

Drag across the chart to create a selection. The preview logs the brushed domain and exposes a reset control above the chart.

Usage

const [brushDomain, setBrushDomain] = useState<[Date, Date] | null>(null);

<Chart.Root
  data={data}
  height={360}
  brush
  onBrush={setBrushDomain}
>
  <Chart.XAxis
    label="Time"
    domain={brushDomain ?? undefined}
    nice={false}
  />
  {/* series */}
</Chart.Root>

Props

Chart.Root
Prop	Type	Default	Description
brush	boolean	false	Enables the interactive brush overlay that lets users select a time window.
onBrush	(domain: [Date, Date] \| null) => void	—	Callback invoked whenever the brush selection changes. Receive `null` when cleared.
marginRight	number	auto	Ensure there is enough space for the brush handles when using secondary axes.

Implementation tips

Persist the brush domain in parent state so you can apply it to `Chart.XAxis` or other filters.
Provide a reset affordance whenever the brush is active to restore the default domain quickly.
Large datasets benefit from throttling updates triggered by the brush callback; debounce if you pipe the selection into network requests.