Metric Card

pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-demo

This Pattern is part of Siteplane UI Pro, and its source comes with a Pro license. Its previews are free to view and try.

Installation

pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card

Usage

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

<MetricCard title="Views in 24 hours" value="2,000" change="12%" />;

Simple figure

The default layout shows the title, the figure and its change in a badge. Pass menuItems for a three-dot menu in the corner and actions for a footer below a divider. A link button with ms-auto moves a single destination to the end of the footer.

In a narrow card the badge moves under the figure, and a chart stays beside them, so the figure never runs under the badge. The width at which this happens follows from the parts the card shows, such as a comparison or a chart, and stays the same however long their text is.

pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-simple-example

Icon above the title

Pass an icon to show it above the title. The icon is bare, without a frame, and decorative. icon-top tints it with the success color and keeps the change in a badge. icon-top-inline keeps the icon in the text color and sets the change and its comparison at the end of the figure’s row.

pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-icon-top-example

Icon beside the title

icon-heading puts the icon in the accent color in front of the title and moves the change below the figure. icon-leading gives the icon a column of its own before the title and the figure and keeps the change in a badge.

Set iconTone="neutral" to draw the icon in the secondary text color, --sp-rw-fg-secondary, in every layout: in place of the accent of icon-heading and figure-inline, the success color of icon-top and the text color of the other layouts. A neutral icon suits a module icon and leaves color to states, such as the trend of the change.

pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-icon-side-example

Chart beside the figure

Pass series to draw a chart, one array of numbers per series. chart-aside sets a small chart at the end of the card with the change below the figure. chart-overlay layers several series as soft overlapping areas and takes an icon in front of the title.

pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-chart-side-example

Full-width chart

chart-full draws the chart across the card below the figure. chart-frame moves the title into a header above a divider and draws the chart across the panel.

pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-chart-full-example

Figures without a card

The figure layouts show the figure without its card, for figures inside a card or a panel. figure sets the title as a label above the value and the change in a badge after the value, which moves below it when the figure has no room beside it. figure-large sets the value at the size of the card layouts, for the first and larger figure of a row, and figure is one step smaller. A comparison is a quieter line under the figure. figure-inline is a small figure for a compact row: an optional icon in the accent color, the title on one line and the value after it.

Each figure is a description list of its own, so several sit side by side in a row that you lay out, such as flex flex-wrap. The figure layouts take no menu, actions or chart. Place the figures inside the card they describe rather than as a strip of cards above a list.

pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-figures-example

Long titles

A long title wraps by default. Set titleLines to cut it after that many lines with an ellipsis instead, so cards side by side keep one height; hovering a cut title shows it in full in a tooltip. The title stays the card's heading with its whole text, so assistive technology reads all of it. titleLines uses Truncate, which the Pattern installs.

pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-title-lines-example

Falling trend

Set trend="down" for a decrease. The arrow turns downward and the change and the chart take the destructive color. The card does not decide whether a change is good; it shows the direction you pass.

pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-trend-example

Changing data

When new data arrives, the card moves to it. A value or change with digits rolls to its new value, written as you pass it; the comparison, other content and a turned trend fade through; the chart morphs into the new series. The card keeps its height, because the change lays out by the width of its area, whatever the length of its text.

pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-changing-example

API reference

MetricCardProps and MetricCardVariant export these contracts. The card is built from Card, Badge, Button, Menu, Separator, Sparkline, Motion and Truncate, and fills the width of its container; a figure without a card is as wide as its content, up to the width of its container. It takes no native div props or ref beyond className. Formatting the figure, calculating the change and loading data stay with the application.

Usage notes

Name the measure in title and the period in comparison; a change without its period is ambiguous. The arrow is hidden from assistive technology and the change is plain text, so state a fall in change, for example -3.1%, and let an unsigned value mean a rise.

The chart is a sparkline without axes, labels or hover values. Show exact numbers in the figure and the change, and describe the shape in chartLabel, for example “Views per two hours, rising”.

A series of one point, or a change in the number of series, shows at once instead of morphing. With reduced motion, from the system setting or SiteplaneMotionProvider preset="reduced", all new data shows at once. In a narrow card, comparison text much longer than “vs. last quarter” can still wrap and add a line, and a long figure with a comparison can crowd the change. The menu button keeps a column of its own: the title keeps its room, and so does the figure in the chart-frame layout, where the change moves under the value before it would reach the button. A figure wider than its column wraps between its characters, and a long title wraps, so neither runs under the button or past the card; titleLines cuts the title instead.

When several cards share a page, give each menu its own menuLabel so assistive technology can tell the menu buttons apart. Place the cards in a grid to build a row of metrics, and keep their loading, empty and error states in the application. Figures that belong to one card or panel go inside it in the figure layouts.