Surface chart

Pro

One value over two variables, drawn as a surface you can turn. It is orthographic, with no perspective, so a tall point is tall from every side. Cells over the threshold turn ember, and the top view is the same data as a heatmap.

Installs components/ui/surface-chart.tsxDepends on @radix-ui/react-slot, lucide-reactMotion shared motion tokens

pnpm dlx shadcn@latest add @caliper/surface-chart

p95 latency by request rate and cache hit rate
cache hits \ rps	0	308	692	1,000	1,308	1,692	2,000
30%	44 ms	58 ms	88 ms	145 ms	260 ms	264 ms	332 ms
41%	44 ms	57 ms	85 ms	157 ms	328 ms	255 ms	302 ms
54%	44 ms	57 ms	82 ms	133 ms	243 ms	219 ms	263 ms
65%	44 ms	56 ms	78 ms	108 ms	156 ms	186 ms	231 ms
76%	44 ms	56 ms	76 ms	96 ms	123 ms	161 ms	198 ms
89%	44 ms	55 ms	72 ms	87 ms	105 ms	131 ms	154 ms
100%	44 ms	55 ms	68 ms	79 ms	90 ms	103 ms	114 ms

1,538 rps · 43% cache hits · p95 283 ms · over the 250 ms SLO

under the thresholdover the 250 ms SLOOrthographic: heights compare honestly.

When to use #

Use it for

Response surfaces: latency by load and cache hit rate, yield by temperature and time.
Finding where a value falls off a cliff.

Skip it when

One variable, or two categories; use a line or a heatmap.
Exact comparison; the top view and the table are for that.

Decisions #

Why it is built this way, so you know what to keep when you change your copy.

Behaviour

A probe you can read: Click or use the arrows to stand the probe on a cell; its value is written out in a live region, not only drawn.
Paused when idle: It paints only while it is turning or when something changes, and repaints when the theme does.

Styling

No perspective: Heights compare honestly. Perspective would make the near edge look taller than the far one.

Installation #

terminal

pnpm dlx shadcn@latest add @caliper/surface-chart

Adds its 8 files to components/ui/, each with its own stylesheet, and installs their packages. Pro installs with your access token, set up once per project. See Pro access. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage #

Import it from your copy of the source. The example behind the preview comes with the source.

example.tsx

import { SurfaceChart } from "@/components/ui/surface-chart"

The worked example comes with Pro

The 28-line example behind the preview opens here with a Pro or Team licence.

Checking your licence…

API reference #

SurfaceChart

component

PropTypeDefaultDescription

label *string—

x *SurfaceAxis—The axis along the bottom, left to right.

y *SurfaceAxis—The axis into the screen, front to back.

z *readonly (readonly number[])[]—One array per y step, one number per x step. At least 2 by 2.

zLabel *string—What the height is, for example "p95 latency".

zFormat((value: number) => string)(n: number) => String(Math.round(n))

thresholdnumber—Cells above this value turn ember.

thresholdLabelstring"over the threshold"

statusDepthStatus"ready"

messagesDepthMessages—

onRetry(() => void)—

disabledboolean—

classNamestring—

Motion #

Transitions use the shared duration and easing tokens. Under prefers-reduced-motion those tokens collapse to instant and travel distances go to zero, so state changes still happen without movement.