Foundations

Regions

Regions highlight contextual windows—cooling cycles, comfort bands, maintenance periods—so operators can quickly scan timelines. They register alongside other marks and honour secondary axes.

Example

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

The demo layers time-based cooling regions (blue) and a comfort band (green) on top of temperature and pressure series.

Usage

<Chart.Root data={data} height={360}>
  <Chart.Region
    type="time"
    start={cycle.start}
    end={cycle.end}
    color="var(--ambient-data-series-6)"
    opacity={0.12}
  />
  <Chart.Region
    type="value"
    start={72}
    end={78}
    color="var(--ambient-data-series-3)"
    opacity={0.08}
    label="Comfort band"
  />
</Chart.Root>

Props

Chart.Region
Prop	Type	Default	Description
type	`"time" \| "value"`	—	Choose `time` to shade along the x-axis or `value` for horizontal bands tied to y-values.
start	DomainInput	—	Start boundary. Accepts `Date`, timestamp, or numeric value depending on region type.
end	DomainInput	—	End boundary matching the same units as `start`. Regions are inclusive.
label	string	—	Optional label rendered inside the shaded region when space allows.
color	string	Theme region token	Fill colour. Use CSS variables for consistency across themes.
opacity	number	0.12	Opacity applied to the region fill.
axis	string	`"y"`	Bind value regions to a named secondary axis to match transformed scales.

Recommendations

Keep opacity below 0.2 so the underlying series remain legible.
Use value regions to communicate acceptable operating envelopes and time regions for discrete events.
When binding to a secondary axis, pass the same `axis` name used on the associated `Chart.YAxis` and series.