Metric

If your project doesn't have Wisty UI's theme yet, add it once with npx shadcn@latest add @wisty/cosmos. Until then, components keep shadcn's default look. Installation has the details.

The trend's text and its change come from the same number, so the arrow and the words never disagree. Format the value before you pass it, with a fixed locale, so server and client print the same text. A word unit takes a space before it, as it's written ({days} <MetricUnit>days</MetricUnit>); a percent sign takes none. formatMetricValue formats a number as KPI row and Metric trend do: written out under 10,000, compact from there to three significant digits ("$4.82M"). formatMetricChange writes the change from a previous value as signed text: a percent of it, points for a percent format, and the difference itself when the previous value is 0. A sparkline, a card title in place of the label, and the loading state are shown by the In a card, with a sparkline and Loading examples.

SLDS has no metric component. Its Charts guidelines name Metric as an intent, and Lightning's dashboard Metric shows one value. The parts follow SLDS's type classes and the meaning of its trend icon, slds-icon-trend; the table lists the class behind each part. The trend's arrow is Lucide's, turned as SLDS turns its own. While loading, the value and the trend are Skeleton.

Known gaps:

• SLDS's trend icon draws a circle around the arrow and can animate it. The metric draws the arrow only, and never animates it.

• A metric is plain text in reading order: label, value, trend. Metric adds no role. A metric with no MetricLabel needs a name right before it, like a card title, or role="group" with aria-labelledby pointing at one.
• The arrow is hidden from screen readers, so the trend's text must carry the sign and the comparison ("+16% vs last quarter"). Good or bad is in the color only; when it matters, write it too ("+12% vs last week, worse").
• A sparkline is decoration. Wrap it in aria-hidden="true" and give the chart accessibilityLayer={false}, so it takes no tab stop, and say what it shows in the trend's text.
• A loading metric is aria-busy, with no text in its value and trend, so a screen reader never hears a stale or zero figure.

• The value doesn't animate, so a changed figure jumps into place. The loading placeholders pulse, and hold still when the user prefers reduced motion.

• A metric fills the width of its parent. Put metrics in a grid or a wrapping row with a gap.
• A long label wraps. The value doesn't shrink, so keep values compact ("$1.2M", not "$1,240,000").

• A sparkline is a full chart. Keep to a few per page, with a few dozen points each.

• Pass the signed change from the data as change, never a literal. When a rise is bad, add isIncreasePositive={false}; never flip the sign to get a color.
• Give a sparkline isAnimationActive={false} and <YAxis hide domain={["dataMin", "dataMax"]} />. Without the axis the line sits flat near the top instead of showing its shape.
• While the number loads, pass loading on Metric and render the same parts as when loaded, so the placeholders match what replaces them. Never show a zero, a dash or a stale figure in their place.
• A currency symbol belongs in the formatted value, not in MetricUnit.
• Never pass asChild or render.