affectUI › Components › Data display

Stat Card

One number with its label, how it changed – green or red, lower can be better – and room for a chart below or beside it; numbers roll, the card can be a link.

Part of affectUI Pro. Install: npx shadcn@latest add https://www.affectui.com/r/stat-card.json · Import from @/components/ui/stat-card

When to use

  • The KPI row on top of a dashboard – spend, tokens, latency, error rate
  • One number with how it changed against the period before, and a small chart under or beside it
  • Cards that open a detail view – pass href or onClick and the whole card becomes the target

When not to use

  • A chart that needs axes and a full tooltip – put a Trend Chart in a card of its own
  • Many numbers in one table – a Data Table reads better than a wall of cards

Usage

import { StatCard } from "@/components/ui/stat-card";
import { TrendChart } from "@/components/ui/trend-chart";

export function Spend() {
  return (
    <StatCard
      label="Spend"
      value={2741}
      format={(n) => `$${(n / 1000).toFixed(1)}k`}
      change={16.5}
      changeLabel="vs last week"
      chart={
        <TrendChart
          variant="sparkline"
          labels={["Mar 3", "Mar 4", "Mar 5", "Mar 6"]}
          series={[{ label: "Spend", values: [412, 455, 398, 470] }]}
        />
      }
    />
  );
}

Props

NameTypeDefaultDescription
labelstringWhat the number is
valuenumber | stringA number rolls when it changes and is shown through format; a string is shown as it is
format(n: number) => string1,284 / 2.5BFormats a number value
changenumberChange in percent against the period before – colored text with an arrow
changeFormat(n: number) => string"12.4%"Formats the change; gets the absolute value
changeLabelstringQuiet text after the change, e.g. "vs last week"
lowerIsBetterbooleanfalseA rise is bad news – red – and a fall good news – green
iconReactNodeA 16px icon before the label
chartReactNodeAny chart – a Trend Chart sparkline fits it exactly
layout"stacked" | "inline""stacked"The chart below the number or to its right
footerReactNodeThe card's last row
loadingbooleanfalsePlaceholders instead of number, change and chart – the card keeps its size
hrefstringMakes the whole card a link
onClick() => voidMakes the whole card a button
hitPropsHTMLAttributesExtra attributes for the link or button – e.g. role="tab", aria-selected and tabIndex when the cards pick what a chart shows
actionReactNodeA small control in the top right corner – a menu or filter; stays clickable on a link card
selectedbooleanOne card of a set is picked: false fades the card's content
classNamestringExtra class on the card
styleCSSPropertiesInline styles on the card, e.g. CSS variables
--ui-stat-skel-hCSS variable44pxHeight of the chart placeholder while loading – match it to a taller chart

Keyboard

  • Tab: Focus the card when it is a link or a button, then the chart inside it
  • Enter: Open the card's link or press its button

Accessibility

  • Screen readers hear the final value and the change in words ("up 16.5% vs last week"), never a number on its way
  • A link or button card names its label, value and change; the chart inside stays reachable on its own
  • While loading the card is marked busy

Responsive

  • Fills its grid cell; the value wraps rather than being cut, the label and comparison end in an ellipsis
  • Dark mode built in: switches when an ancestor (usually <html>) has the class dark or data-theme="dark"

Requirements

  • React 19

Related

  • Trend Chart – The chart on its own for any card or layout – line, area, bars or a sparkline from the same data, with a tooltip, this period against the last, and charts that follow the same day together
  • KPI Chart – Metric card with a multi-line chart and a tooltip that follows the pointer
  • Usage Meter – Plan usage and AI credits – a stacked credits meter by category, daily sparkline, limits and a button that speaks up near the limit