Stat

Common Stat Variants

Size Variants

Trend Indicator Styles

• Arrow + Percentage: ↑ 12.3% — Most common, clear and compact
• Arrow only: ↑ — When the exact delta isn't important
• Color-coded value: The value itself turns green/red — Use sparingly, as color alone fails WCAG SC 1.4.1
• Background tint: Subtle green/red background behind the trend — Requires sufficient contrast per Contrast Checker

Stat Properties

Important: Never rely solely on color to convey trend direction. Always pair color with an icon (arrow) or text ("+"/"-") to satisfy WCAG SC 1.4.1 (Use of Color). Screen readers need the trend communicated via text, not color.

Design Token Mappings

Use font-variant-numeric: tabular-nums on stat values so digits maintain consistent widths. This prevents layout shifts when values change (e.g., animated counters going from 999 to 1,000).

Stat States

Animation note: Count-up animations are engaging but can be disorienting. Always disable them when prefers-reduced-motion: reduce is active — show the final value immediately instead.

Accessibility Requirements

Semantic Structure:

• Wrap each stat in a <div> or <figure> with descriptive labeling. For a group of stats, use <dl> (description list) with <dt> for labels and <dd> for values — this is the most semantically correct approach.
• Use aria-label or aria-labelledby to associate the value with its label for screen readers.

WCAG Compliance:

• SC 1.4.1 (Use of Color): Trend indicators must not rely on color alone. Pair green/red with directional arrows or "+"/"-" text. Verify trend colors against backgrounds with the Contrast Checker.
• SC 1.4.3 (Contrast – Minimum): Value text (large, bold) typically qualifies for the 3:1 large-text ratio. Label text requires the standard 4.5:1 ratio.
• SC 1.4.11 (Non-text Contrast): Trend arrows and icons need 3:1 contrast against their background.
• SC 1.3.1 (Info and Relationships): Use <dl>/<dt>/<dd> or aria-labelledby to programmatically convey that "Total Revenue" and "$1,234,567" are associated.
• SC 4.1.2 (Name, Role, Value): If a stat is clickable (links to a detail page), it must have role="link" or be wrapped in an <a> tag.

Screen Reader Experience: A stat reading "Total Revenue: $1,234,567. Up 12.3% from last month." is ideal — concise and informative. Avoid reading the raw number without context.

Live Updates: If stat values update in real-time (WebSocket, polling), use aria-live="polite" to announce changes without interrupting the user. Use aria-atomic="true" so the entire stat is re-read, not just the changed digit.

Usage Guidelines

Do:

• Limit dashboard headers to 3–6 stats maximum. Beyond that, cognitive load increases and nothing stands out.
• Use consistent formatting across stats in the same row — all percentages, all currency, or all counts. Mixing formats forces context-switching.
• Place the most important stat first (left in LTR layouts). Eye-tracking shows the first position gets 2–3× more fixations.
• Provide a "Last updated" timestamp or relative time for data-driven stats.
• Use tabular numerals (font-variant-numeric: tabular-nums) so values align vertically in grids.

Don't:

• Don't display raw database numbers without formatting — "1234567.89" is unreadable; "$1,234,568" is instant.
• Don't use abbreviations without full-value tooltips — "1.2M" is ambiguous without knowing the exact figure.
• Don't make every stat clickable. If a stat links to a detail view, make the interaction obvious with a hover effect or explicit "View details" link.
• Don't animate stats on every re-render. Count-up animations should only fire on initial load, not on data refresh.
• Don't use more than two trend colors (typically green/red). Additional colors (yellow, blue) confuse the directionality signal.

Material Design 3 does not provide a dedicated Stat component. Developers typically compose stats from Typography, Card, and Stack components. MUI's Typography with variant="h3" for the value and variant="body2" for the label is the standard pattern. Community libraries like @mui/x-charts offer sparkline components that pair well with custom stat cards.

Ant Design provides a Statistic component with title, value, prefix, suffix, precision (decimal places), formatter, valueStyle, and a Statistic.Countdown subcomponent for timer displays. Ant's implementation handles number formatting automatically using toLocaleString() and supports groupSeparator customization. The formatter prop accepts the value and renders a ReactNode, enabling custom formatting like colored text or embedded icons.

Chakra UI provides a Stat compound component with StatLabel, StatNumber, StatHelpText, StatArrow (renders up/down arrow with appropriate green/red color), and StatGroup (flex container with spacing). Chakra's StatArrow automatically sets aria-label="increased" or aria-label="decreased" — a thoughtful accessibility detail. The StatGroup uses flexbox with flexWrap="wrap" for responsive layouts.

Radix UI and Headless UI do not provide Stat primitives, as the component is primarily presentational with no complex interaction patterns requiring headless abstraction.

Tremor (React library for dashboards) provides an excellent Metric and BadgeDelta combination that serves as a stat component with built-in trend indicators, sparklines via SparkAreaChart, and responsive card layouts. Tremor's approach is dashboard-first and worth studying for stat design patterns.