Plot · Smallest

Playground

Open Show controls to switch Domain and Live, and to try the axes, legend, inspection and range.

Call volume

Time series. Use Left and Right arrows to inspect values, Home and End for range edges, and Escape to clear.

Domain

A fixed historical range. Pass the full domain once; ranges narrow the window from its end and sit in the card's top bar.

Call volume

Time series. Use Left and Right arrows to inspect values, Home and End for range edges, and Escape to clear.

import { useState } from "react";
import { PlotCard } from "@smallest-inc/ui";

const DAY = 86_400;
const END = Date.UTC(2026, 8, 28) / 1000;

/** Calls per day for the last 30 days, oldest first. */
const CALLS = [
  1116, 1174, 1258, 864, 923, 1280, 1313, 1245, 1312, 1320, 988, 890, 1393, 1351, 1411, 1320, 1417, 934,
  979, 1467, 1437, 1315, 1423, 1405, 1089, 1017, 1483, 1462, 1449, 1450,
];

const data = CALLS.map((value, index) => ({ time: END - (CALLS.length - 1 - index) * DAY, value }));

const RANGES = [
  { id: "7d", label: "7D", secs: 7 * DAY },
  { id: "14d", label: "14D", secs: 14 * DAY },
  { id: "30d", label: "30D", secs: 30 * DAY },
];

export default function PlotDomain() {
  const [range, setRange] = useState("30d");

  return (
    <PlotCard
      title="Call volume"
      series={[{ id: "calls", label: "Calls", color: "#0069F5", data }]}
      domain={{
        domain: { start: data[0].time, end: END },
        ranges: RANGES,
        rangeId: range,
        onRangeChange: setRange,
      }}
    />
  );
}

Live

A sliding window anchored to now. Append points as they arrive; windows set the span, and paused freezes the scroll without dropping data.

Concurrent calls

Time series. Use Left and Right arrows to inspect values, Home and End for range edges, and Escape to clear.

import { useEffect, useState } from "react";
import type { PlotPoint } from "@smallest-inc/plot";
import { Button, PlotCard } from "@smallest-inc/ui";

/** Stand-in for a websocket feed: one sample every 250ms. */
function sample(time: number): PlotPoint {
  return { time, value: 42 + 8 * Math.sin(time / 6) + 3 * Math.sin(time / 1.7) };
}

function useConcurrentCalls() {
  const [data, setData] = useState<PlotPoint[]>(() => {
    const now = Date.now() / 1000;
    return Array.from({ length: 120 }, (_, index) => sample(now - (119 - index) * 0.5));
  });

  useEffect(() => {
    const id = setInterval(() => {
      setData((previous) => [...previous.slice(-600), sample(Date.now() / 1000)]);
    }, 250);
    return () => clearInterval(id);
  }, []);

  return { data, value: data.at(-1)?.value ?? 0 };
}

export default function PlotLive() {
  const { data, value } = useConcurrentCalls();
  const [paused, setPaused] = useState(false);

  return (
    <div className="flex w-full flex-col items-start gap-4">
      <PlotCard
        mode="live"
        title="Concurrent calls"
        series={[{ id: "concurrent", label: "Concurrent calls", color: "#0069F5" }]}
        paused={paused}
        formatValue={(v) => Math.round(v).toString()}
        live={{
          data,
          value,
          defaultWindow: 60,
          windows: [
            { label: "30s", secs: 30 },
            { label: "1m", secs: 60 },
            { label: "2m", secs: 120 },
          ],
        }}
      />
      <Button variant="secondary" size="sm" onClick={() => setPaused((current) => !current)}>
        {paused ? "Resume" : "Pause"}
      </Button>
    </div>
  );
}

Multi-series

Each series needs an id, label and color. Legend buttons hide a series and rescale the Y axis; at least one stays visible.

Call volume

Time series. Use Left and Right arrows to inspect values, Home and End for range edges, and Escape to clear.

import { PlotCard } from "@smallest-inc/ui";

const DAY = 86_400;
const END = Date.UTC(2026, 8, 28) / 1000;

/** Daily totals for the last 30 days, oldest first. */
const TOTAL = [
  1116, 1174, 1258, 864, 923, 1280, 1313, 1245, 1312, 1320, 988, 890, 1393, 1351, 1411, 1320, 1417, 934,
  979, 1467, 1437, 1315, 1423, 1405, 1089, 1017, 1483, 1462, 1449, 1450,
];
const ANSWERED = [
  908, 889, 985, 691, 723, 1012, 997, 992, 977, 1026, 795, 695, 1108, 1062, 1147, 1012, 1086, 713, 748,
  1151, 1164, 1002, 1111, 1061, 811, 781, 1207, 1101, 1105, 1122,
];

const daily = (values: number[]) =>
  values.map((value, index) => ({ time: END - (values.length - 1 - index) * DAY, value }));

export default function PlotMultiSeries() {
  return (
    <PlotCard
      title="Call volume"
      legend="values"
      series={[
        { id: "total", label: "Total calls", color: "#0069F5", data: daily(TOTAL) },
        { id: "answered", label: "Answered", color: "#8B5CF6", data: daily(ANSWERED) },
      ]}
      domain={{ domain: { start: END - 29 * DAY, end: END } }}
    />
  );
}

Bucket inspection

inspection="bucket" treats each bucketWidth as a window: the scrub snaps to exact observations and highlights that segment of the line. Use it when each value is a whole period, like calls per day.

Calls per day

Time series. Use Left and Right arrows to inspect values, Home and End for range edges, and Escape to clear.

import { PlotCard } from "@smallest-inc/ui";

const DAY = 86_400;
const END = Date.UTC(2026, 8, 28) / 1000;

/** Calls per day for the last 14 days, oldest first. */
const CALLS = [1245, 1312, 1320, 988, 890, 1393, 1351, 1411, 1320, 1417, 934, 979, 1467, 1437];

const data = CALLS.map((value, index) => ({ time: END - (CALLS.length - 1 - index) * DAY, value }));

// Daily buckets start at midnight UTC: label them by day, not by clock time.
const formatDay = (time: number) =>
  new Date(time * 1000).toLocaleDateString("en-US", { month: "short", day: "numeric", timeZone: "UTC" });
const formatWeekday = (time: number) =>
  new Date(time * 1000).toLocaleDateString("en-US", { weekday: "short", timeZone: "UTC" });

/** Each day is a window: hovering snaps to it and highlights that segment of the line. */
export default function PlotBucket() {
  return (
    <PlotCard
      title="Calls per day"
      inspection="bucket"
      bucketWidth={DAY}
      hoverHighlight="segment"
      formatTooltipDate={formatDay}
      formatTooltipTime={formatWeekday}
      series={[{ id: "calls", label: "Calls", color: "#0069F5", data }]}
      domain={{ domain: { start: data[0].time, end: END } }}
    />
  );
}

Guide lines

overlays registers reference lines such as a cap or target; visibleOverlays turns them on. currentPriceLineSeriesIds adds a dashed line at a series' latest value.

Peak concurrency

Time series. Use Left and Right arrows to inspect values, Home and End for range edges, and Escape to clear.

import { PlotCard } from "@smallest-inc/ui";

const DAY = 86_400;
const END = Date.UTC(2026, 8, 28) / 1000;

/** Peak concurrent calls per day, oldest first. */
const PEAK = [48, 52, 61, 39, 41, 57, 63, 58, 66, 69, 44, 40, 71, 64];

const data = PEAK.map((value, index) => ({ time: END - (PEAK.length - 1 - index) * DAY, value }));

export default function PlotGuideLines() {
  return (
    <PlotCard
      title="Peak concurrency"
      series={[{ id: "peak", label: "Peak concurrent calls", color: "#0069F5", data }]}
      overlays={[{ id: "cap", value: 70, label: "Plan limit" }]}
      visibleOverlays={["cap"]}
      currentPriceLineSeriesIds={["peak"]}
      domain={{ domain: { start: data[0].time, end: END } }}
    />
  );
}

Loading

loading draws a breathing line in place of the data, at the card's full height.

Call volume

Loading chart.

Loading data…

Empty

When the range has no points, emptyText replaces the line with a hint to change the range or filters.

Call volume

No calls in this periodTry another date range or adjust your filters.

Error

error shows your message; pass onRetry to add a Try again action.

Call volume

Couldn’t load call volume

import { PlotCard } from "@smallest-inc/ui";

const END = Date.UTC(2026, 8, 28) / 1000;

export default function PlotError() {
  return (
    <PlotCard
      title="Call volume"
      error="Couldn’t load call volume"
      onRetry={() => {
        // Refetch the series here.
      }}
      legend="none"
      series={[{ id: "calls", label: "Calls", color: "#0069F5", data: [] }]}
      domain={{ domain: { start: END - 30 * 86_400, end: END } }}
    />
  );
}

Best practices

When to use

Use PlotCard for a titled time series on analytics pages: call volume, concurrency, latency.
Use SpotlightChart when several KPIs share one time range and tabs swap the series. Use Stat Strip when the KPIs need no chart.
Use raw Plot from @smallest-inc/plot only when you need engine features without card chrome, such as candlesticks (chartType="candle", lineMode) or a custom header.

Behavior

mode defaults to domain: a fixed { start, end } with optional ranges tabs that narrow the window from its end. Use mode="live" for a sliding window anchored to now, with windows and defaultWindow.
The parent owns mode. The card never renders a Domain/Live switch.
Put data on series ({ id, label, color, data }) for domain. For live, keep series as metadata and stream points through live.data or live.series with matching ids.
Scrub is continuous by default. Use inspection="bucket" (plus bucketWidth when the gap cannot be inferred) to snap to exact observations. A missing bucket stays empty.
axes is both by default: x draws time labels and y draws the value grid. Use axes="none" for sparkline-size cards.
Guide lines are off by default. Register them with overlays, turn them on with visibleOverlays, and add dashed current-value lines with currentPriceLineSeriesIds.
Multi-series cards have no fill by default. Use areaFill="lower" so fills never add up visually; use overlap only when every series is a subset of the one above it.
Legend buttons hide series and rescale Y. At least one series always stays visible.
loading, emptyText and error (with onRetry) replace the plot while keeping the card's height. paused freezes a live feed without dropping points.

Content

Title the card with the metric ("Call volume"), not the chart type. Series labels are nouns in sentence case ("Answered").
Pass formatValue and formatLegendValue that match the product KPI copy, for example rounded counts and "690 ms". formatValue receives the series id.
Give each series a distinct hex color. Canvas colors cannot read CSS variables.
Credit Liveline (MIT) from packages/plot/NOTICE when shipping.

Accessibility

Pass accessibleLabel when title is not plain text. Focusing the plot lets people inspect points with Left/Right and Home/End; Escape clears.
Legend buttons expose aria-pressed. Do not rely on color alone for multi-series; keep labels in the legend.
Put a summary or table beside the chart for anything people must read exactly.