Kappa / Timeseries

<script setup lang="ts">
import {
  TimeseriesChart,
  type TimeseriesChartPoint,
  type TimeseriesChartSeries,
} from "@dicehub/kappa/components/timeseries-chart";
import { LineChart } from "echarts/charts";
import { GridComponent, LegendComponent, TooltipComponent } from "echarts/components";
import * as echarts from "echarts/core";
import { CanvasRenderer } from "echarts/renderers";

echarts.use([LineChart, GridComponent, LegendComponent, TooltipComponent, CanvasRenderer]);

const hour = 60 * 60 * 1000;
const start = Date.UTC(2026, 8, 22);
const toPoints = (values: number[]): TimeseriesChartPoint[] =>
  values.map((value, index) => [start + index * hour, value]);
const compute = [46, 51, 58, 55, 62, 66, 59, 53];
const storage = [31, 34, 36, 39, 42, 44, 47, 50];
const series: TimeseriesChartSeries[] = [
  { name: "Compute", type: "area", curve: "smooth", data: toPoints(compute) },
  { name: "Storage", curve: "smooth", data: toPoints(storage) },
];
</script>

<template>
  <TimeseriesChart
    :engine="echarts"
    :series="series"
    title="Platform utilization"
    aria-label="Compute and storage utilization"
    aria-description="Compute peaks at 66 percent. Storage rises to 50 percent."
    y-label="Utilization (%)"
    :y-min="0"
    :y-max="100"
    time-zone="utc"
  />
</template>

Installation

TimeseriesChart uses the optional ECharts peer dependency. Import it from its isolated component path so applications that do not draw charts do not load ECharts.

pnpm add @dicehub/kappa echarts

Usage

Supply timestamp and value pairs inside each named series. Timestamps use Unix milliseconds. Replace the series reference, or update revision after a controlled in-place mutation.

<script setup lang="ts">
import {
  TimeseriesChart,
  type TimeseriesChartPoint,
  type TimeseriesChartSeries,
} from "@dicehub/kappa/components/timeseries-chart";
import { LineChart } from "echarts/charts";
import { GridComponent, LegendComponent, TooltipComponent } from "echarts/components";
import * as echarts from "echarts/core";
import { CanvasRenderer } from "echarts/renderers";

echarts.use([LineChart, GridComponent, LegendComponent, TooltipComponent, CanvasRenderer]);

const hour = 60 * 60 * 1000;
const start = Date.UTC(2026, 8, 22);
const toPoints = (values: number[]): TimeseriesChartPoint[] =>
  values.map((value, index) => [start + index * hour, value]);
const compute = [46, 51, 58, 55, 62, 66, 59, 53];
const storage = [31, 34, 36, 39, 42, 44, 47, 50];
const series: TimeseriesChartSeries[] = [
  { name: "Compute", type: "area", curve: "smooth", data: toPoints(compute) },
  { name: "Storage", curve: "smooth", data: toPoints(storage) },
];
</script>

<template>
  <TimeseriesChart
    :engine="echarts"
    :series="series"
    title="Platform utilization"
    aria-label="Compute and storage utilization"
    aria-description="Compute peaks at 66 percent. Storage rises to 50 percent."
    y-label="Utilization (%)"
    :y-min="0"
    :y-max="100"
    time-zone="utc"
  />
</template>

This component configures the existing ECharts Chart host for dashboard time data. It owns the grid, axes, safe rich-text tooltip, legend, theme, and motion defaults. Use the lower-level Chart component when the visualization needs a different ECharts shape.

Set a chart-wide type and curve, or override them on one series.
Use null for a missing sample. Set connectNulls only when joining the gap is valid.
Use the toolbar, loading, empty, error, and footer slots for product-specific content.
Use valueFormatter for units. Kappa keeps the standard tooltip in ECharts rich-text mode.

Examples

Counts as Bars

Use bars for discrete values collected in fixed time buckets.

<script setup lang="ts">
import { BarChart } from "echarts/charts";

// Register BarChart with the same ECharts engine used in the main example.
echarts.use([BarChart]);
</script>

<template>
  <TimeseriesChart
    :engine="echarts"
    :series="[{ name: 'Completed', type: 'bar', data: completed }]"
    type="bar"
    aria-label="Completed tasks by hour"
    aria-description="Hourly counts peak at 81."
    y-label="Tasks"
    :y-min="0"
    :y-min-interval="1"
  />
</template>

Missing Data

Keep missing intervals visible. Opt into connectNulls only when joining the gap is truthful.

const series = [
  {
    name: "Primary",
    data: [[time[0], 41], [time[1], 44], [time[2], null], [time[3], 55]],
  },
  {
    name: "Replica",
    curve: "step",
    data: [[time[0], 31], [time[1], 33], [time[2], 35], [time[3], 38]],
  },
];

<TimeseriesChart
  :engine="echarts"
  :series="series"
  aria-label="Storage throughput"
  aria-description="The primary series has a data gap."
/>

Stacked Area

Show how related series contribute to a total without exposing ECharts option plumbing.

<TimeseriesChart
  :engine="echarts"
  :series="[
    { name: 'Cached', type: 'area', stack: 'requests', data: cached },
    { name: 'Origin', type: 'area', stack: 'requests', data: origin },
  ]"
  type="area"
  aria-label="Stacked request volume"
  aria-description="Cached requests make up most of the traffic."
  :y-min="0"
/>

UTC and Locale

Choose UTC or browser-local labels and an explicit display locale.

<TimeseriesChart
  :engine="echarts"
  :series="series"
  time-zone="utc"
  locale="en-GB"
  aria-label="Active connections in UTC"
  aria-description="Connections rise from 12 to 25."
/>

Data States

Keep loading, empty, and error behavior inside the same stable frame.

<TimeseriesChart :engine="echarts" :series="series" loading ... />
<TimeseriesChart :engine="echarts" :series="[]" empty empty-label="No samples in this range" ... />
<TimeseriesChart :engine="echarts" :series="series" error="The data query failed." ... />

Performance

Use TimeseriesChart for normal dashboard ranges and visual quality. For 100,000 or more samples, sustained live telemetry, or scientific X/Y data, use XYPlot. Kappa does not switch engines at runtime.

Accessibility

ariaLabel names the graphic. ariaDescription explains the range, units, series, and main trend.
The pointer tooltip is supplementary. Put its essential meaning in the accessible description or a linked data table.
Reduced-motion preferences turn off chart animation.
Do not identify a series by color alone. Keep the legend or another visible label.

API Reference

Prop	Type	Default	Description
`engine`	`ChartEngine`	`required`	Configured modular ECharts namespace.
`series`	`TimeseriesChartSeries[]`	`required`	Named series with Unix-millisecond timestamp and value pairs.
`ariaLabel / ariaDescription`	`string`	`required`	Accessible name and plain-language data summary.
`type`	`"line" \| "area" \| "bar"`	`"line"`	Default rendering type. A series can override it.
`curve`	`"linear" \| "smooth" \| "step"`	`"linear"`	Default line interpolation. A series can override it.
`timeZone`	`"local" \| "utc"`	`"local"`	Axis and tooltip time zone.
`locale`	`string`	`browser`	Locale for time and numeric axis labels.
`showLegend / showGrid / tooltip`	`boolean`	`true`	Visible chart furniture.
`animation`	`boolean`	`true`	Animate normal updates. Reduced-motion preferences always take priority.
`yMin / yMax / yMinInterval`	`number \| data bound`	`—`	Optional value-axis bounds and tick interval.
`loading / empty / error`	`boolean / boolean / string`	`false / false / —`	Explicit data states.
`events`	`ChartEvents`	`—`	Stable ECharts event-to-handler map.
`revision`	`string \| number`	`0`	Reapply data after a controlled in-place mutation.

Exposed Methods

Method	Description
`getInstance / resize`	Read or resize the ECharts instance.
`setOption / dispatchAction`	Use advanced ECharts operations without replacing the component.

Import the component and its public types from @dicehub/kappa/components/timeseries-chart. The module exports TimeseriesChart, TimeseriesChartProps, TimeseriesChartSeries, and TimeseriesChartApi.