@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.
- 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.
Anatomy
Section titled “Anatomy”<Chart> <Chart.Plot> <Chart.Grid /> <Chart.XAxis /> <Chart.YAxis /> <Chart.Line /> <Chart.Tooltip /> </Chart.Plot> <Chart.Legend /> <Chart.Table /></Chart>Installation
Section titled “Installation”-
Install the package and its peer. The
sveltepeer is^5.40.0.Terminal window pnpm add @viamrobotics/prime-charts @viamrobotics/tailwind-configTerminal window npm install @viamrobotics/prime-charts @viamrobotics/tailwind-configTerminal window yarn add @viamrobotics/prime-charts @viamrobotics/tailwind-config -
Import the stylesheet once, after Tailwind. Tailwind skips
node_moduleswhen 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.
Several series
Section titled “Several series”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.
Code
<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>Bounds
Section titled “Bounds”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.
Code
<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>Formatters
Section titled “Formatters”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.
Code
<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>Hiding a series
Section titled “Hiding a series”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.
Code
<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>Layout
Section titled “Layout”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.
Code
<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>Stacked charts
Section titled “Stacked charts”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.
Code
<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>States
Section titled “States”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.
No data.
Code
<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>Screen readers
Section titled “Screen readers”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.
| Time |
|---|
Code
<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>Styling
Section titled “Styling”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.
Keyboard
Section titled “Keyboard”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.
| Key | Action |
|---|---|
| ArrowLeft / ArrowRight | Move to the previous or next point in the series |
| ArrowUp / ArrowDown | Move to the previous or next visible series, at its point nearest in time |
| Home / End | Move to the first or last point of the series |
| PageUp / PageDown | Move by a tenth of the series |
| Escape | Hide the tooltip and keep focus on the plot |
| Enter / Space | On 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.
| Prop | Type | Default | Description |
|---|---|---|---|
x | ChartScale | 'time' | The kind of x scale. Defaults to 'time'. |
xMin | Date | number | The lower x bound. Left out, it comes from the data. | |
xMax | Date | number | The upper x bound. Left out, it comes from the data. | |
yMin | number | The lower y bound, used exactly. Left out, it comes from the data, rounded out to the next tick. | |
yMax | number | The upper y bound, used exactly. Left out, it comes from the data, rounded out to the next tick. | |
loading | boolean | false | Lays an overlay on the plot and keeps the last lines drawn underneath. |
empty | Snippet | Rendered in place of the plot when no series has a point. Defaults to the text "No data". | |
children | Snippet | Chart.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
| Prop | Type | Default | Description |
|---|---|---|---|
name | string | Labels the series in the legend and the tooltip. | |
points | ChartPoint<TXValue>[] | The series to draw, in x order. A null y is a gap. | |
unit | string | Shown 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. | |
loading | boolean | false | Shows the series' loading mark in the legend. |
bind:hidden | boolean | false | Hides the series. The legend toggles it, and a hidden series keeps its color and position. |
class | ClassValue |
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.