Metric card

• Type: Component (data)
• Access: Free, open source
• Page: https://ui.xzero.co.uk/components/metric-card
• Markdown: https://ui.xzero.co.uk/components/metric-card/markdown
• Registry item: https://mcp.xzero.co.uk/r/metric-card.json
• Source file: registry/components/metric-card/metric-card.tsx
• Dependencies: motion
• Keywords: data, summary, react metric card, kpi card, odometer number, rolling number card, dashboard metric, stat tile

When to use

• A single plain number with odometer style rolling digits, such as uptime or orders.
• Numbers that update live and should roll in the direction they moved.

When not to use

• Use stat-card for preformatted strings, trend arrows, tones, and icons.
• Use sparkline when the trend over time matters more than the latest value.
• Use animated-counter for a number without a card around it.

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui/metric-card

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { MetricCard } from "@/components/xzero/metric-card/metric-card";

export function Uptime() {
  return <MetricCard label="Uptime" value={99.9} suffix="%" context="Last 30 days" change="+0.2%" />;
}

API reference

MetricCard

A compact card with a label, an odometer style number, context line, and optional change chip.

Prop	Type	Default	Description
label (required)	string	–	What is measured.
value (required)	number	–	The number. Rolls up from zero on first view, then between values.
suffix	string	–	Text after the number, such as "%" or " ms".
context (required)	string	–	Line under the number, such as "vs last week".
change	string	–	Chip in the top corner, such as "+12%". Omit to hide it.

Accessibility

• Renders an article; the number is read as plain text through a visually hidden copy.
• The change chip is plain text, so write the direction into it (+ or -) rather than relying on color.
• It does not announce updates; wrap it in a live region if values change while people watch.

Motion

• The value uses animated-counter: digits roll on view and turn the way the number moved.
• Label, context, and change copy roll in from the direction the number moved, and the chip width springs.
• Reduced motion jumps the digits and swaps copy with a quick fade.

Responsive behavior

• Below 380px the padding tightens and the change chip wraps under the label instead of crowding it.
• Copy lines stay on one line and clip, so keep label and context short.

Performance

• Digits roll with animated-counter and a ResizeObserver drives the chip width spring; a dashboard row of cards is fine.

Notes for AI

• Use when the value is a plain number and you want the rolling digits. Use stat-card for preformatted strings, trend arrows, tones, and icons.
• value must be a number; put units in suffix and formatting-free context in context.

Related

• Animated counter: Give changing totals a clear sense of movement.
• Sparkline: Show a compact trend beside a value.
• Gauge: Show a value against a known range.

Also in cards

• Card: A contained group of related content and actions.
• Empty state: A useful next step when there is nothing to show yet.
• Metric ticker: A strip of live KPIs that roll to new values digit by digit and flash their change; rest on one to pause the strip and open its recent trend as a sparkline.

Guidance for AI tools

Metric card: A compact summary for a number that needs context. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt