Skip to content

@viamrobotics/prime-charts

@viamrobotics/prime-charts is a set of Svelte 5 charts built on LayerCake. They draw with Viam’s design tokens, so they follow the light and dark themes. Chart is a compound component for cartesian charts with a time axis on x and a number axis on y.

No data.

No data
  • Several series on one chart, each with a palette color by position or a color you pick from the tokens.
  • Axes, a grid, a tooltip, and a legend, each a part you place only when you want it.
  • Bounds you set on either axis, or leave to the data.
  • Keyboard navigation of the points and a live region that announces the active point.
<Chart>
<Chart.Plot>
<Chart.Grid />
<Chart.XAxis />
<Chart.YAxis />
<Chart.Line />
<Chart.Tooltip />
</Chart.Plot>
<Chart.Legend />
<Chart.Table />
</Chart>
  1. Install the package and its peer. The svelte peer is ^5.40.0.

    Terminal window
    pnpm add @viamrobotics/prime-charts @viamrobotics/tailwind-config
  2. Import the stylesheet once, after Tailwind. Tailwind skips node_modules when it scans for classes, so the package’s stylesheet points it at the compiled components.

    @import "tailwindcss";
    @import "@viamrobotics/prime-charts/styles.css";

Chart has no layout of its own. Chart.Plot takes and measures the size you give it through its class, such as class="h-64", and a plot with no height draws nothing. It draws inside its content box, so padding in its class insets the drawing. Place the drawing parts inside Chart.Plot, and place Chart.Legend in the Chart before or after the plot. A part outside the plot throws, and so does a second Chart.Plot. Chart needs an accessible name, either aria-label or aria-labelledby. Each Chart.Line takes points, a list of { x, y } where x is a Date or epoch milliseconds and y is a number or null for a gap. An x the time scale cannot place, such as a string or an invalid Date, drops like a gap.

Each Chart.Line takes the next palette color, --color-chart-series-1 to --color-chart-series-7 in the order the lines mount, which is source order on first render. A line that mounts later inside an {#if} takes the next color and the last legend slot. Pass color a CSS variable name to pick another token. A unit shows after the series name in the legend and after its value in the tooltip.

One y axis serves every series, so series with different units share it and the axis shows no unit of its own.

No data.

No data
Code
Series.svelte
<script lang="ts">
import { Chart, type ChartPoint } from "@viamrobotics/prime-charts";
const START_TIME = Date.UTC(2026, 0, 1);
const HOUR = 60 * 60 * 1000;
const COUNT = 24;
const pointsFor = (base: number, swing: number, phase: number): ChartPoint[] =>
Array.from({ length: COUNT }, (_, index) => ({
x: new Date(START_TIME + index * HOUR),
y: base + swing * Math.sin(index / 3 + phase),
}));
const cell01 = pointsFor(40, 12, 0);
const cell02 = pointsFor(55, 8, 1.5);
const pressure = pointsFor(30, 5, 3);
</script>
<Chart aria-label="Cell readings" class="flex flex-col gap-2">
<Chart.Plot class="h-64">
<Chart.Grid />
<Chart.XAxis />
<Chart.YAxis />
<Chart.Line name="cell-01" unit="°" points={cell01} />
<Chart.Line name="cell-02" unit="°" points={cell02} />
<Chart.Line name="pressure" unit="kPa" color="--color-chart-series-5" points={pressure} />
<Chart.Tooltip />
</Chart.Plot>
<Chart.Legend />
</Chart>

Set xMin, xMax, yMin, or yMax to fix an edge. A given bound is used exactly. A bound you leave out comes from the data, and a y bound from the data is rounded out to the next tick. The first chart below fixes the y axis and the second fixes a window on x and the bottom of y.

No data.

No data

No data.

No data
Code
Bounds.svelte
<script lang="ts">
import { Chart, type ChartPoint } from "@viamrobotics/prime-charts";
const START_TIME = Date.UTC(2026, 0, 1);
const HOUR = 60 * 60 * 1000;
const COUNT = 24;
const points: ChartPoint[] = Array.from({ length: COUNT }, (_, index) => ({
x: new Date(START_TIME + index * HOUR),
y: 40 + 12 * Math.sin(index / 3),
}));
const windowStart = new Date(START_TIME + 6 * HOUR);
const windowEnd = new Date(START_TIME + 18 * HOUR);
</script>
<div class="flex flex-col gap-6">
<Chart aria-label="Fixed bounds" yMin={0} yMax={100}>
<Chart.Plot class="h-56">
<Chart.Grid />
<Chart.XAxis />
<Chart.YAxis />
<Chart.Line name="cell-01" unit="°" {points} />
<Chart.Tooltip />
</Chart.Plot>
</Chart>
<Chart aria-label="Bounds from the data" xMin={windowStart} xMax={windowEnd} yMin={0}>
<Chart.Plot class="h-56">
<Chart.Grid />
<Chart.XAxis />
<Chart.YAxis />
<Chart.Line name="cell-01" unit="°" {points} />
<Chart.Tooltip />
</Chart.Plot>
</Chart>
</div>

Chart.XAxis and Chart.YAxis take a format for their tick labels. Chart.Tooltip takes xFormat and yFormat, which each default to the format of the matching axis. Without any of them, the ticks use the time scale’s own format and the tooltip shows a full date and time with the value through Intl.NumberFormat.

No data.

No data
Code
Formatters.svelte
<script lang="ts">
import { Chart, type ChartPoint } from "@viamrobotics/prime-charts";
const START_TIME = Date.UTC(2026, 0, 1);
const HOUR = 60 * 60 * 1000;
const COUNT = 24;
const points: ChartPoint[] = Array.from({ length: COUNT }, (_, index) => ({
x: new Date(START_TIME + index * HOUR),
y: 40 + 12 * Math.sin(index / 3),
}));
const hourFormat = new Intl.DateTimeFormat("en-US", {
hour: "numeric",
timeZone: "UTC",
});
const fullFormat = new Intl.DateTimeFormat("en-US", {
dateStyle: "medium",
timeStyle: "short",
timeZone: "UTC",
});
const formatHour = (value: Date): string => hourFormat.format(value);
const formatDegrees = (value: number): string => `${value.toFixed(0)}°`;
const formatTime = (value: Date): string => fullFormat.format(value);
const formatReading = (value: number): string => `${value.toFixed(2)} degrees`;
</script>
<Chart aria-label="Formatted readings">
<Chart.Plot class="h-64">
<Chart.Grid />
<Chart.XAxis format={formatHour} />
<Chart.YAxis format={formatDegrees} />
<Chart.Line name="cell-01" points={points} />
<Chart.Tooltip xFormat={formatTime} yFormat={formatReading} />
</Chart.Plot>
</Chart>

The legend renders one toggle button per series. Bind hidden on a Chart.Line to read or set the state from outside. Unbound, the line keeps the state itself. A hidden series keeps its color and position, and the axes follow the series that remain visible.

No data.

No data
Code
Hiding.svelte
<script lang="ts">
import { Chart, type ChartPoint } from "@viamrobotics/prime-charts";
const START_TIME = Date.UTC(2026, 0, 1);
const HOUR = 60 * 60 * 1000;
const COUNT = 24;
const pointsFor = (base: number, swing: number, phase: number): ChartPoint[] =>
Array.from({ length: COUNT }, (_, index) => ({
x: new Date(START_TIME + index * HOUR),
y: base + swing * Math.sin(index / 3 + phase),
}));
const cell01 = pointsFor(40, 12, 0);
const cell02 = pointsFor(55, 8, 1.5);
let cell02Hidden = $state(true);
</script>
<div class="flex flex-col gap-4">
<label class="flex items-center gap-2 text-sm">
<input type="checkbox" bind:checked={() => !cell02Hidden, (shown) => (cell02Hidden = !shown)} />
Show cell-02
</label>
<Chart aria-label="Hideable series" class="flex flex-col gap-2">
<Chart.Plot class="h-64">
<Chart.Grid />
<Chart.XAxis />
<Chart.YAxis />
<Chart.Line name="cell-01" unit="°" points={cell01} />
<Chart.Line name="cell-02" unit="°" points={cell02} bind:hidden={cell02Hidden} />
<Chart.Tooltip />
</Chart.Plot>
<Chart.Legend />
</Chart>
</div>

Chart renders its children in whatever layout its class gives it, so the legend goes wherever you place it. Make the Chart a flex row and let the plot take the rest of the width. In a flex flex-col chart, class="min-h-0 flex-1" on the plot fills the height the chart is given.

No data.

No data
Code
Layout.svelte
<script lang="ts">
import { Chart, type ChartPoint } from "@viamrobotics/prime-charts";
const START_TIME = Date.UTC(2026, 0, 1);
const HOUR = 60 * 60 * 1000;
const COUNT = 24;
const pointsFor = (base: number, swing: number, phase: number): ChartPoint[] =>
Array.from({ length: COUNT }, (_, index) => ({
x: new Date(START_TIME + index * HOUR),
y: base + swing * Math.sin(index / 3 + phase),
}));
const cell01 = pointsFor(40, 12, 0);
const cell02 = pointsFor(55, 8, 1.5);
</script>
<Chart aria-label="Legend beside the plot" class="flex h-64 gap-4">
<Chart.Plot class="min-w-0 flex-1">
<Chart.Grid />
<Chart.XAxis />
<Chart.YAxis />
<Chart.Line name="cell-01" unit="°" points={cell01} />
<Chart.Line name="cell-02" unit="°" points={cell02} />
<Chart.Tooltip />
</Chart.Plot>
<Chart.Legend class="flex-col gap-y-2 self-start" />
</Chart>

Each axis sizes its gutter to its labels, so two charts with different y labels start their plots at different x positions. Give each Chart.YAxis the same min-w-* in its class, at least as wide as the widest label, and the plots line up. The gap after the tick marks sits outside the class element, so min-w-* bounds the labels alone. A min-w-24 clears 15,000 req/h at text-xs, which measures 72px. A padding or border you add to the column counts toward its width.

No data.

No data

No data.

No data
Code
Stacked.svelte
<script lang="ts">
import { Chart, type ChartPoint } from "@viamrobotics/prime-charts";
const START_TIME = Date.UTC(2026, 0, 1);
const HOUR = 60 * 60 * 1000;
const COUNT = 24;
const pointsFor = (base: number, swing: number, phase: number): ChartPoint[] =>
Array.from({ length: COUNT }, (_, index) => ({
x: new Date(START_TIME + index * HOUR),
y: base + swing * Math.sin(index / 3 + phase),
}));
const temperature = pointsFor(40, 12, 0);
const throughput = pointsFor(12000, 3000, 1.5);
const formatDegrees = (value: number) => `${Math.round(value)}°`;
const formatThroughput = (value: number) => `${Math.round(value).toLocaleString("en-US")} req/h`;
</script>
<div class="flex flex-col gap-4">
<Chart aria-label="Temperature over a day">
<Chart.Plot class="h-40">
<Chart.Grid />
<Chart.XAxis />
<Chart.YAxis class="min-w-24" format={formatDegrees} />
<Chart.Line name="temperature" points={temperature} />
<Chart.Tooltip />
</Chart.Plot>
</Chart>
<Chart aria-label="Throughput over a day">
<Chart.Plot class="h-40">
<Chart.Grid />
<Chart.XAxis />
<Chart.YAxis class="min-w-24" format={formatThroughput} />
<Chart.Line name="throughput" points={throughput} />
<Chart.Tooltip />
</Chart.Plot>
</Chart>
</div>

empty replaces the plot when no series has a point, and defaults to the text “No data”. loading lays an overlay on the plot and keeps the last lines underneath. Loading wins over the empty state. A loading prop on a line shows its loading mark in the legend.

No data.

Nothing recorded for this range

No data.

Code
States.svelte
<script lang="ts">
import { Chart, type ChartPoint } from "@viamrobotics/prime-charts";
const START_TIME = Date.UTC(2026, 0, 1);
const HOUR = 60 * 60 * 1000;
const COUNT = 24;
const points: ChartPoint[] = Array.from({ length: COUNT }, (_, index) => ({
x: new Date(START_TIME + index * HOUR),
y: 40 + 12 * Math.sin(index / 3),
}));
</script>
<div class="flex flex-col gap-6">
<Chart aria-label="Empty chart">
<Chart.Plot class="h-48">
<Chart.Grid />
<Chart.XAxis />
<Chart.YAxis />
<Chart.Line name="cell-01" points={[]} />
</Chart.Plot>
{#snippet empty()}
<span>Nothing recorded for this range</span>
{/snippet}
</Chart>
<Chart aria-label="Loading chart" loading class="flex flex-col gap-2">
<Chart.Plot class="h-48">
<Chart.Grid />
<Chart.XAxis />
<Chart.YAxis />
<Chart.Line name="cell-01" loading {points} />
</Chart.Plot>
<Chart.Legend />
</Chart>
</div>

The figure carries a visually hidden summary, linked through aria-describedby. It lists the visible series and the ranges of time and values, such as Series: cell-01 (°), cell-02 (°). Time: Jan 1, 2026, 12:00:00 AM to Jan 1, 2026, 6:00:00 AM. Values: 12 to 48., with the series labeled as the legend labels them and each end formatted with the axis formats, then the tooltip defaults. An empty chart reads No data. and a chart with every series hidden reads Every series is hidden. Pass your own aria-describedby to Chart and it replaces the summary, which then does not render.

Chart.Table is opt-in. It renders the visible series as a table with a Time column and one column per series, labeled like the legend, and one row per time inside the x window. A series with no value at a time leaves an empty cell. The table is visible by default. Its class lands on a wrapper around the table, so class="sr-only" keeps it for screen readers only and never grows the page. It takes a caption, and without one it takes its name from the chart’s aria-label, or from aria-labelledby when the chart has one. Like the other parts, it formats time and values with the axis formats, then the tooltip defaults.

No data.

No data
Resource use
Time
Code
DataTable.svelte
<script lang="ts">
import { Chart, type ChartPoint } from "@viamrobotics/prime-charts";
const START_TIME = Date.UTC(2026, 0, 1);
const HOUR = 60 * 60 * 1000;
const COUNT = 6;
const cpu: ChartPoint[] = Array.from({ length: COUNT }, (_, index) => ({
x: new Date(START_TIME + index * HOUR),
y: 40 + 12 * Math.sin(index / 2),
}));
const memory: ChartPoint[] = Array.from({ length: COUNT }, (_, index) => ({
x: new Date(START_TIME + index * HOUR),
y: index === 3 ? null : 60 + 8 * Math.cos(index / 2),
}));
</script>
<Chart aria-label="Resource use" class="flex flex-col gap-4">
<Chart.Plot class="h-48">
<Chart.Grid />
<Chart.XAxis />
<Chart.YAxis />
<Chart.Line name="CPU" unit="%" points={cpu} />
<Chart.Line name="Memory" unit="%" points={memory} />
<Chart.Tooltip />
</Chart.Plot>
<Chart.Legend />
<Chart.Table class="w-full" />
</Chart>

class lands on a different element for each part.

Part Where class lands
Chart The root element, which has the figure role
Chart.Plot The plot element, sized through its class
Chart.Line The path, or the circle of a single point
Chart.Grid The <g> that holds the grid lines
Chart.XAxis The row of tick labels below the plot
Chart.YAxis The column of tick labels beside the plot
Chart.Tooltip The tooltip box
Chart.Legend The list
Chart.Table A wrapper around the <table>, with no layout of its own

An axis class styles the tick labels only. The axis line and tick marks take their color from the --color-chart-axis token. The labels default to text-xs in the axis label color.

The axes size their gutters to their labels, and each side takes the larger of what the parts reserve on it. On Chart.YAxis, a font size changes the look and the column width, a color changes the look and no gutter, and a min-w-* sets a least width for the labels. On Chart.XAxis, a font size changes the look and the row height, a color changes no gutter, and a min-w-* has no effect. A border or padding on an axis class counts toward its gutter. A margin does not, so it moves the labels out of the plot’s box.

Every other attribute on Chart also goes to the root element. Colors come from the chart tokens in @viamrobotics/tailwind-config, such as --color-chart-series-1, so a literal color has no place in a class or in color.

The package sets these data-part attributes, so a variant like [&_[data-part=legend-item]]:text-xs reaches them from the root.

data-part Element
plot The plot element, which takes its class
loading The overlay over the plot while loading
empty The box that holds the empty content
legend The legend list
legend-item A legend toggle button
legend-swatch A series color swatch in the legend
legend-loading A series loading mark in the legend
tooltip The tooltip box
tooltip-marker The dot on the active point
tooltip-swatch The series color swatch in the tooltip
summary The visually hidden figure summary
table The data table inside the Table wrapper

The root has aria-busy while loading. Each legend button has aria-pressed, which is true while its series is visible.

Tab order follows DOM order, so a legend placed before Chart.Plot puts its buttons ahead of the plot. The plot is a tab stop when a Chart.Tooltip is placed and a visible series has a point inside the x window. Focusing the plot shows the tooltip on the active point. On first focus that is the first point inside the window of the first visible series that has one, and after that it is the point focus left. Hidden series, gaps, and points outside the window are skipped. Every key and the pointer stay inside the window, and a point exactly on a bound is inside.

KeyAction
ArrowLeft / ArrowRightMove to the previous or next point in the series
ArrowUp / ArrowDownMove to the previous or next visible series, at its point nearest in time
Home / EndMove to the first or last point of the series
PageUp / PageDownMove by a tenth of the series
EscapeHide the tooltip and keep focus on the plot
Enter / SpaceOn a legend button, toggle the series

A polite live region announces the active point as the tooltip reads it, and the visible tooltip is aria-hidden. The plot has role="application", with its instructions linked through aria-describedby. The figure itself is described by the visually hidden summary, so a screen reader reads what the chart holds before the plot.

PropTypeDefaultDescription
xChartScale'time'The kind of x scale. Defaults to 'time'.
xMinDate | numberThe lower x bound. Left out, it comes from the data.
xMaxDate | numberThe upper x bound. Left out, it comes from the data.
yMinnumberThe lower y bound, used exactly. Left out, it comes from the data, rounded out to the next tick.
yMaxnumberThe upper y bound, used exactly. Left out, it comes from the data, rounded out to the next tick.
loadingbooleanfalseLays an overlay on the plot and keeps the last lines drawn underneath.
emptySnippetRendered in place of the plot when no series has a point. Defaults to the text "No data".
childrenSnippetChart.Plot, which holds the drawing parts, and Chart.Legend, in the layout the consumer writes.

Plus everything in HTMLAttributes<HTMLDivElement>, spread onto the element.

Requires one of aria-label or aria-labelledby.

Chart.Grid

Takes className }: Props as its props.

Chart.Legend

Takes className }: Props as its props.

Chart.Line

PropTypeDefaultDescription
namestringLabels the series in the legend and the tooltip.
pointsChartPoint<TXValue>[]The series to draw, in x order. A null y is a gap.
unitstringShown after the series name in the legend, and after its value in the tooltip.
color`--${string}`A CSS variable such as '--color-chart-series-4'. Defaults to the palette slot for the line's position.
loadingbooleanfalseShows the series' loading mark in the legend.
bind:hiddenbooleanfalseHides the series. The legend toggles it, and a hidden series keeps its color and position.
classClassValue

Chart.Plot

Takes className, children }: Props as its props.

Chart.Table

Takes className }: Props as its props.

Chart.Tooltip

Takes className }: Props as its props.

Chart.XAxis

Takes className }: Props as its props.

Chart.YAxis

Takes className }: Props as its props.