One headline number on a card: label, value, change and context, coloured only when the change is for the worse; a link, loading and unavailable state, and MetricGrid for the row.
Robots online
2 docked for charging12/ 14
+1, betterPatrol hours
Last 7 days286h
+8%, betterEvents
3 need review24
+6, worseAvg. battery
Lowest: 9C44 at 18%71%
−2%Metric card row
Install
npx shadcn add @syncrobotic/metric-card Also installs: lucide-react, @syncrobotic/cn, @syncrobotic/card, @syncrobotic/skeleton
Overview
When to use
- The row of numbers under a dashboard's page header: robots online, events, devices, API calls.
- A count that opens the list behind it (with
href).
Use something else
- A level in a known range (battery, storage, signal): Meter.
- A number with a chart under it: a Card with CardDataHeader and CardFigure.
- Several values about one thing (a robot's facts): Description list.
More examples
States and real uses. Each example is also a Storybook story and a visual regression test.
Unplanned stops
Against last week3
−4, betterEvents
Against last week24
+6, worseMissions done
Against last week968
+0.2%Metric card trends
2 docked for charging
3 need review
Metric card with link
Robots online
Loading
Patrol hours
Loading
Events
Loading
Avg. battery
Loading
Metric card loading
Open incidents
Both at Taoyuan plant2
Avg. mission time
Within the usual range18min
+0.3 minMetric card without sparkline
Usage rules
- Only a change for the worse is coloured (
trend="bad", danger text). Good news stays foreground and no change stays grey, so the bad number is the one people see. The trend says whether the change is good, not which way it went. - The sparkline is neutral and silent; the delta and the caption say in words what it shows. From 640 px it sits beside the value; on a phone it takes its own full-width line under it, and the change sits under the label so the values line up.
- A value that cannot be read is
unavailablewith the reason; never a 0 or an empty card. loadingkeeps the label and the card's height; only the value, change and caption are bones.hrefmakes the whole card one link (passlinkAsfor your router); give it only when a page sits behind the number.- Put the cards in a MetricGrid: two across from the smallest phone, four from 1280 px. One row under the page header, what needs someone (alarms) above it.
- A level in a known range (battery, storage, signal) is a Meter, not a metric card.
Changelog
- 0.19.02026-11-20Sparkline on phones too, on its own full-width line under the value. No change ("0", "±0", "0.0 %") has no arrow: a change of nothing has no direction.
- 0.18.02026-11-19First release: MetricCard (label, value and unit, delta coloured only when trend is bad with better/worse read aloud, neutral sparkline, caption; href makes the card one link; loading keeps its height; unavailable shows a dash and why) and MetricGrid, taken out of stats-cards.