);
}
```
### When down is good
positive="down" turns a falling error rate green and a rising bill red. Neutral metrics stay grey.
```tsx
"use client";
import { Cloud, OctagonAlert, Rocket } from "@/components/ui/icons";
import { Stat, StatGroup } from "@/components/ui/stat";
// For these, down is good: green arrows point down, red ones up.
export default function StatInverted() {
return (
);
}
```
### Loading
Skeletons hold the value, delta and sparkline in place, so nothing jumps when data lands.
```tsx
"use client";
import * as React from "react";
import { Button } from "@/components/ui/button";
import { RefreshCw, Repeat } from "@/components/ui/icons";
import { Stat } from "@/components/ui/stat";
export default function StatLoading() {
const [loading, setLoading] = React.useState(true);
const [run, setRun] = React.useState(0);
React.useEffect(() => {
if (!loading) return;
const timer = setTimeout(() => setLoading(false), 1400);
return () => clearTimeout(timer);
}, [loading, run]);
return (
);
}
```
## API reference
### Stat
Renders a div with role="group", named by its label. Accepts every native div attribute.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `ReactNode` | — | What the number is. Sentence case, no colon. Wraps rather than truncating. |
| `icon` | `Icon` | — | A NeonKit icon, drawn as a tinted glass tube with a core. It lights up when live. |
| `value` | `number \| string` | — | A number counts up and is formatted; a string is shown as is. |
| `format` | `(value: number) => string` | — | Formats the value, including every frame of the count-up. |
| `formatOptions` | `Intl.NumberFormatOptions` | — | Options for the default formatter, e.g. currency. Decimals follow the value otherwise. |
| `locale` | `string` | `"en-US"` | Locale for the default formatter. Fixed by default so server and client agree. |
| `unit` | `ReactNode` | — | Smaller text after the value, such as ms or %. |
| `delta` | `number` | — | Change since the comparison period. Its sign sets the arrow. |
| `formatDelta` | `(delta: number) => ReactNode` | `12.4%` | Formats the delta's absolute value. The arrow carries the sign. |
| `positive` | `"up" \| "down" \| "neutral"` | `"up"` | Which direction is good. Sets green or red; neutral stays grey. |
| `trend` | `number[]` | — | Draws a Sparkline. |
| `trendPlacement` | `"bottom" \| "end"` | `"bottom"` | Full width under the value, or small beside it. Beside it wraps under the value when the cell is narrow. |
| `goal` | `number` | — | A target for a numeric value. Draws a tube meter that fills toward it. |
| `helper` | `ReactNode` | — | A line under the value, usually the comparison period. |
| `countUp` | `boolean` | `true` | Counts up on mount and eases between later values. Skipped under reduced motion. |
| `live` | `boolean` | `false` | Lights the icon (or shows a heartbeat dot), pings the sparkline end and flashes on every update. |
| `loading` | `boolean` | `false` | Skeletons in place of the value, delta and sparkline. Sets aria-busy. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Value set at 24, 32 or 44px. |
| `color` | `NeonColor` | `inherited` | Palette name or hex for the sparkline and live dot. Falls back to --neon-accent, then cyan. |
### StatGroup
A grid of stats split by hairlines. Accepts every native div attribute.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `count, up to 4` | Columns at full width. It steps down to two, then one on narrow screens. |
| `variant` | `"plain" \| "framed"` | `"plain"` | Hairlines only, or with an outer border and surface. |
| `color` | `NeonColor` | `inherited` | Color for every stat inside. |
## Accessibility
- Assistive tech reads the final value once; the counting digits are hidden from it.
- The delta says Up or Down in words, so color is never the only signal.
- Live stats don't announce each tick, which would talk over the page. Put a live region around the one value that matters if you need it.
- The count-up reserves the final value's width, so the delta and sparkline don't shift while it runs.
- In a narrow cell the delta and an end sparkline wrap under the value instead of overlapping it.
- Under prefers-reduced-motion the value appears at once and the heartbeat dot holds still.
## Source
`components/ui/stat.tsx`
```tsx
"use client";
import * as React from "react";
import { ArrowDownRight, ArrowUpRight, Minus, type Icon } from "@/components/ui/icons";
import { cn } from "@/lib/utils";
import { neonVars, type NeonColor } from "@/lib/neon";
import { Sparkline } from "@/components/ui/glow-chart";
import { Skeleton } from "@/components/ui/skeleton";
// Lub-dub: two quick beats, then rest. The ring only goes out on the first beat.
const css = `
@keyframes nk-stat-beat {
0%, 36%, 100% { transform: scale(1); }
9% { transform: scale(1.4); }
22% { transform: scale(1.22); }
}
@keyframes nk-stat-ring {
0% { transform: scale(1); opacity: 0.7; }
45%, 100% { transform: scale(3.2); opacity: 0; }
}
`;
const useIsomorphicLayoutEffect = typeof window !== "undefined" ? React.useLayoutEffect : React.useEffect;
const sizes = {
sm: {
value: "text-2xl leading-8",
unit: "text-sm",
skeleton: "h-8 w-24",
icon: "size-4",
spark: { inline: 80, height: 28 },
},
md: {
value: "text-[2rem] leading-10",
unit: "text-base",
skeleton: "h-10 w-32",
icon: "size-[18px]",
spark: { inline: 96, height: 36 },
},
lg: {
value: "text-[2.75rem] leading-[3.25rem]",
unit: "text-lg",
skeleton: "h-[52px] w-40",
icon: "size-5",
spark: { inline: 120, height: 48 },
},
} as const;
const tones = {
good: "green",
bad: "red",
neutral: undefined,
} as const;
/** Decimals in a number as written, so a count-up to 99.5 shows one decimal the whole way. */
function decimalsOf(value: number) {
if (!Number.isFinite(value) || Number.isInteger(value)) return 0;
const [, fraction = ""] = String(value).split(".");
return Math.min(fraction.length, 4);
}
function prefersReducedMotion() {
return typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
}
function defaultGoal(share: number) {
return `${Math.round(share * 100)}% of goal`;
}
function defaultDelta(delta: number) {
return `${Math.abs(delta).toLocaleString("en-US", { maximumFractionDigits: 1 })}%`;
}
/**
* The icon as a glass tube: a colored outer tube with a hot core drawn inside it. Unlit it's tinted glass with a
* cold core; lit (live) the core goes white and the tube throws a halo.
*/
function TubeIcon({ icon: Glyph, lit, className }: { icon: Icon; lit: boolean; className: string }) {
return (
svg]:[grid-area:1/1] [&>svg]:size-full", className)}
>
);
}
export interface StatProps extends Omit, "color"> {
/** Palette name or any hex color. Inherits `--neon-accent` when omitted. */
color?: NeonColor;
label: React.ReactNode;
/** A NeonKit icon drawn as a tube by the label. It lights up when the stat is live. */
icon?: Icon;
/** A number counts up and formats itself; a string is shown as is. */
value: number | string;
/** Formats a numeric value, including every frame of the count-up. */
format?: (value: number) => string;
/** Intl options for the default formatter, e.g. `{ style: "currency", currency: "USD" }`. */
formatOptions?: Intl.NumberFormatOptions;
locale?: string;
/** Smaller text after the value, e.g. "ms". */
unit?: React.ReactNode;
/** Change since the comparison period. Its sign sets the arrow. */
delta?: number;
formatDelta?: (delta: number) => React.ReactNode;
/** Which direction is good. Latency and churn improve going down. */
positive?: "up" | "down" | "neutral";
/** Data for a Sparkline. */
trend?: number[];
/** `bottom` runs the sparkline the full width under the value; `end` sets a small one beside it. */
trendPlacement?: "bottom" | "end";
/** A target or limit for a numeric value. Draws a tube that fills toward it. */
goal?: number;
/** The line under the goal tube. Gets the share (0–1) and the formatted goal. */
formatGoal?: (share: number, goal: string) => React.ReactNode;
/** A line under the value, e.g. the comparison period. */
helper?: React.ReactNode;
/** Counts the value up on mount and between updates. Off under reduced motion. */
countUp?: boolean;
/** Lights the icon (or a heartbeat dot), pings the sparkline's end and flashes each update. */
live?: boolean;
loading?: boolean;
size?: keyof typeof sizes;
}
const Stat = React.forwardRef(
(
{
className,
style,
color,
label,
icon,
value,
format,
formatOptions,
locale = "en-US",
unit,
delta,
formatDelta = defaultDelta,
positive = "up",
trend,
trendPlacement = "bottom",
goal,
formatGoal = defaultGoal,
helper,
countUp = true,
live = false,
loading = false,
size = "md",
...props
},
ref,
) => {
const id = React.useId();
const labelId = `${id}-label`;
const s = sizes[size];
const numeric = typeof value === "number";
const formatter = React.useMemo(() => {
if (format) return format;
const decimals = numeric ? decimalsOf(value) : 0;
const intl = new Intl.NumberFormat(locale, {
minimumFractionDigits: decimals,
maximumFractionDigits: decimals,
...formatOptions,
});
return (n: number) => intl.format(n);
}, [format, formatOptions, locale, numeric, value]);
const text = numeric ? formatter(value) : value;
const displayRef = React.useRef(null);
const shown = React.useRef(null);
// Read inside the effect without making it re-run when only the formatter's identity changes.
const formatRef = React.useRef(formatter);
useIsomorphicLayoutEffect(() => {
formatRef.current = formatter;
});
useIsomorphicLayoutEffect(() => {
const node = displayRef.current;
if (!node || !numeric || loading) return;
const from = shown.current ?? 0;
const first = shown.current === null;
shown.current = value;
const write = (n: number) => {
node.textContent = formatRef.current(n);
};
if (live && !first && typeof node.animate === "function" && !prefersReducedMotion()) {
node.animate(
[
{
textShadow: "0 0 2px rgb(var(--neon) / calc(0.9 * var(--neon-glow, 1))), 0 0 18px rgb(var(--neon) / calc(0.6 * var(--neon-glow, 1)))",
color: "rgb(var(--neon))",
},
{
textShadow: "0 0 0 transparent",
color: "rgb(255 255 255 / 0.95)",
},
],
{ duration: 900, easing: "cubic-bezier(0.23, 1, 0.32, 1)" },
);
}
if (!countUp || from === value || prefersReducedMotion()) {
write(value);
return;
}
const duration = first ? 1100 : 600;
const start = performance.now();
let frame = 0;
const tick = (now: number) => {
const t = Math.min(1, (now - start) / duration);
const eased = 1 - Math.pow(1 - t, 4);
write(from + (value - from) * eased);
if (t < 1) frame = requestAnimationFrame(tick);
};
write(from);
frame = requestAnimationFrame(tick);
return () => {
cancelAnimationFrame(frame);
write(value);
};
}, [value, numeric, countUp, live, loading]);
const direction = delta === undefined ? null : delta > 0 ? "up" : delta < 0 ? "down" : "flat";
const tone =
direction === null || direction === "flat" || positive === "neutral"
? "neutral"
: direction === positive
? "good"
: "bad";
const DeltaIcon = direction === "up" ? ArrowUpRight : direction === "down" ? ArrowDownRight : Minus;
const hasTrend = Boolean(trend && trend.length > 1);
const goalShare = numeric && goal !== undefined && goal > 0 ? Math.max(0, Math.min(1, value / goal)) : null;
const deltaNode =
direction === null ? null : loading ? (
) : (
{direction === "up" ? "Up" : direction === "down" ? "Down" : "No change,"}
{formatDelta(delta as number)}
);
return (
{/* Wraps instead of colliding: in a narrow cell the delta and an end sparkline drop under the value. */}
{loading ? (
) : (
{text}
{numeric ? (
// The final value holds the width, so nothing beside it moves while it counts.
{text}
{text}
) : (
{text}
)}
{unit && {unit}}
)}
{deltaNode}
{!loading && (
// Width rather than scaleX, which would squash the tube's round ends.
)}
{loading ? "\u00a0" : formatGoal(goalShare, formatter(goal as number))}{formatter(goal as number)}
)}
{helper &&
{helper}
}
);
},
);
Stat.displayName = "Stat";
const columnClasses = {
1: "grid-cols-1",
2: "grid-cols-1 min-[420px]:grid-cols-2",
3: "grid-cols-1 sm:grid-cols-3",
4: "grid-cols-1 min-[420px]:grid-cols-2 lg:grid-cols-4",
5: "grid-cols-1 min-[420px]:grid-cols-2 md:grid-cols-3 xl:grid-cols-5",
6: "grid-cols-1 min-[420px]:grid-cols-2 md:grid-cols-3 xl:grid-cols-6",
} as const;
export interface StatGroupProps extends Omit, "color"> {
/** Palette name or any hex color for every stat inside. */
color?: NeonColor;
/** Columns at full width. Fewer below it. Defaults to the number of stats, up to 4. */
columns?: keyof typeof columnClasses;
/** `framed` adds an outer border; `plain` leaves only the hairlines between stats. */
variant?: "plain" | "framed";
}
const StatGroup = React.forwardRef(
({ className, style, color, columns, variant = "plain", children, ...props }, ref) => {
// toArray resolves the lazy references Server Components can pass, and drops empty slots.
const count = React.Children.toArray(children).length;
const cols = columns ?? (Math.min(Math.max(count, 1), 4) as keyof typeof columnClasses);
return (
{/* Every cell draws its top and left hairline; the wrapper hides the outer ones, however the grid wraps. */}
*]:border-l [&>*]:border-t [&>*]:border-white/[0.08] [&>*]:px-5 [&>*]:py-5",
// Each stat spans four rows of a subgrid, so a label that wraps doesn't push its value below the others.
"[&>[role=group]]:[grid-row:span_4] [&>[role=group]]:[grid-template-rows:subgrid]",
variant === "framed" && "[&>*]:px-6 [&>*]:py-6",
columnClasses[cols],
)}
>
{children}