Timeseries Chart

The timeseries chart is a specialized chart for displaying time-based data. Each data point is a tuple of [timestamp_in_ms, value].

Basic Line Chart

A simple line chart displaying multiple data series over time.

import { TimeseriesChart, ChartPalette } from "@cloudflare/kumo";

const data = [
  {
    name: "Requests",
    color: ChartPalette.semantic("Neutral", isDarkMode),
    data: [
      [timestamp_in_ms, value],
      [timestamp_in_ms, value],
      ...
    ],
  },
  {
    name: "Errors",
    color: ChartPalette.semantic("Attention", isDarkMode),
    data: [
      [timestamp_in_ms, value],
      [timestamp_in_ms, value],
      ...
    ],
  },
];

<TimeseriesChart
  echarts={echarts}
  isDarkMode={isDarkMode}
  data={data}
  xAxisName="Time (UTC)"
  yAxisName="Count"
/>

Use xAxisTickFormat and yAxisTickFormat to control how axis tick labels are rendered. The x-axis formatter receives the raw timestamp in milliseconds; the y-axis formatter receives the raw numeric value. Both return a display string.

Use tooltipValueFormat to control how values appear in the hover tooltip. It receives the raw y-value and returns a display string. When omitted, the raw value is shown.

import { TimeseriesChart, ChartPalette } from "@cloudflare/kumo";

<TimeseriesChart
  echarts={echarts}
  isDarkMode={isDarkMode}
  data={data}
  xAxisName="Time (UTC)"
  yAxisName="Requests"
  xAxisTickFormat={(ts) => {
    const d = new Date(ts);
    return d.getHours().toString().padStart(2, "0")
      + ":" + d.getMinutes().toString().padStart(2, "0");
  }}
  yAxisTickFormat={(value) => {
    if (value >= 1000) return value / 1000 + "k";
    return value.toString();
  }}
  tooltipValueFormat={(value) =>
    (value / 1000).toFixed(1) + "k requests"
  }
/>

Gradient Fill

Set gradient to true to render a vertical gradient fill beneath each line series. The fill fades from the series color at the top to transparent at the bottom, giving the chart a polished area-chart look without losing the clarity of individual lines.

<TimeseriesChart
  echarts={echarts}
  isDarkMode={isDarkMode}
  data={data}
  xAxisName="Time (UTC)"
  yAxisName="Count"
  gradient
/>

Incomplete Data

Use the incomplete prop to indicate regions where data may be incomplete or still being collected.

import { TimeseriesChart, ChartPalette } from "@cloudflare/kumo";

const data = [
  {
    name: "Bandwidth",
    color: ChartPalette.color(0, isDarkMode),
    data: [
      [timestamp_in_ms, value],
      [timestamp_in_ms, value],
      ...
    ],
  },
];

<TimeseriesChart
  echarts={echarts}
  isDarkMode={isDarkMode}
  data={data}
  xAxisName="Time (UTC)"
  yAxisName="Mbps"
  incomplete={{ after: timestamp_in_ms }}
/>

Time Range Selection

Enable time range selection by providing the onTimeRangeChange callback. Users can click and drag on the chart to select a time range.

import { TimeseriesChart, ChartPalette } from "@cloudflare/kumo";

const data = [
  {
    name: "CPU Usage",
    color: ChartPalette.color(0, isDarkMode),
    data: [
      [timestamp_in_ms, value],
      [timestamp_in_ms, value],
      ...
    ],
  },
];

<TimeseriesChart
  echarts={echarts}
  isDarkMode={isDarkMode}
  data={data}
  xAxisName="Time (UTC)"
  yAxisName="%"
  onTimeRangeChange={(from, to) => {
    alert("Selected range: " + from + " - " + to);
  }}
/>

Bar Chart

Set type="bar" to render series as stacked bars instead of lines. All other props — axes, tooltips, colors — work identically.

<TimeseriesChart
  echarts={echarts}
  isDarkMode={isDarkMode}
  type="bar"
  data={data}
  xAxisName="Time (UTC)"
  yAxisName="Count"
/>

Loading State

Set loading to true to display an animated sine-wave skeleton while data is being fetched. The chart canvas is hidden until loading completes; swap back to loading={false} to reveal the chart.

const [isLoading, setIsLoading] = useState(true);

<TimeseriesChart
  echarts={echarts}
  isDarkMode={isDarkMode}
  data={data}
  loading={isLoading}
/>

Kumo