Stat Counter
A dashboard number that rolls to its new value, with a change badge whose arrow flows up or down.
Preview
"use client";
import { useState } from "react";
import { useAutoplay } from "../demo-context";
import { StatCounter } from "./StatCounter";
const days = [
[12840, 11920],
[14215, 12840],
[13380, 14215],
[16902, 13380],
];
export default function Demo() {
const [turn, setTurn] = useState(0);
useAutoplay(() => setTurn((t) => t + 1), 1800);
const [value, previous] = days[turn % days.length];
return (
<StatCounter
label="Revenue today"
value={value}
previous={previous}
format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }}
locale="en-US"
/>
);
}Installation
npx @usefluid/cli add stat-counterpnpm dlx @usefluid/cli add stat-counteryarn dlx @usefluid/cli add stat-counterbunx @usefluid/cli add stat-counterInstall the engine.
Terminal npm i @usefluid/motionCopy these files into your project.
components/fluid/stat-counter/StatCounter.tsx "use client"; import { MorphPath, useSpring } from "@usefluid/motion/react"; import { type CSSProperties, useMemo, useRef, useState } from "react"; import styles from "./StatCounter.module.css"; const UP = "M60 18L102 64H74V102H46V64H18Z"; const DOWN = "M60 102L18 56H46V18H74V56H102Z"; const ROLL = { w: 9, z: 1 }; const tint = (color?: string) => (color ? ({ "--fluid-accent": color, "--fluid-on-accent": "#ffffff" } as CSSProperties) : undefined); const roundLike = (v: number, target: number) => Number(v.toFixed(Math.min(6, (String(target).split(".")[1] ?? "").length))); type Props = { label: string; value: number; previous?: number; format?: Intl.NumberFormatOptions; locale?: string; upIsGood?: boolean; color?: string; }; export function StatCounter({ label, value, previous, format, locale, upIsGood = true, color }: Props) { const out = useRef<HTMLSpanElement>(null); const key = JSON.stringify(format ?? {}); const number = useMemo(() => new Intl.NumberFormat(locale, JSON.parse(key)), [locale, key]); const percent = useMemo(() => new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 1 }), [locale]); const [first] = useState(() => number.format(value)); useSpring( { v: value }, ({ v }) => { if (out.current) out.current.textContent = number.format(roundLike(v, value)); }, ROLL, ); const change = previous === undefined || previous === 0 ? null : (value - previous) / Math.abs(previous); const up = change !== null && change >= 0; const good = up === upIsGood; return ( <div className={styles.card} style={tint(color)}> <span className={styles.label}>{label}</span> <span ref={out} className={styles.value} aria-hidden> {first} </span> <span className={styles.hidden}>{number.format(value)}</span> {change !== null && ( <span className={styles.delta} data-good={good ? "" : undefined}> <svg viewBox="0 0 120 120" width={12} height={12} aria-hidden> <MorphPath d={up ? UP : DOWN} fill="currentColor" config={{ w: 18, z: 0.62 }} /> </svg> <span className={styles.hidden}>{up ? "up" : "down"}</span> {percent.format(Math.abs(change))} </span> )} </div> ); }components/fluid/stat-counter/StatCounter.module.css .card { display: grid; gap: 10px; justify-items: start; min-width: 220px; padding: 22px 24px; border-radius: 24px; background: var(--fluid-surface); color: var(--fluid-text); font-family: var(--fluid-font); } .label { display: inline-flex; align-items: center; gap: 8px; color: var(--fluid-text-2); font-size: 14px; font-weight: 500; } .label::before { width: 8px; height: 8px; border-radius: 999px; background: var(--fluid-accent); content: ""; } .value { font-size: 44px; font-weight: 600; font-variant-numeric: tabular-nums; letter-spacing: -0.03em; line-height: 1; } .delta { display: inline-flex; align-items: center; gap: 6px; height: 28px; padding: 0 12px 0 10px; border-radius: 999px; background: color-mix(in srgb, #e5484d 16%, transparent); color: #e5484d; font-size: 13px; font-weight: 600; font-variant-numeric: tabular-nums; transition: background 300ms ease, color 300ms ease; } .delta[data-good] { background: color-mix(in srgb, #30a46c 16%, transparent); color: #30a46c; } .hidden { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }Import the theme once, then point its variables at your own tokens.
layout.tsx import "@usefluid/motion/theme.css";
Usage
import { StatCounter } from "./StatCounter";
<StatCounter label="Revenue today" value={16902} previous={13380} format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }} />API reference
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | What the number is. |
value | number | — | The number. Change it and the digits roll to it. |
previous | number | — | The value to compare with. The badge shows the change in percent. Leave it out to hide the badge. |
format | Intl.NumberFormatOptions | — | Currency, percent, units and decimals, as in Intl.NumberFormat. |
locale | string | the browser's | Locale for the number. |
upIsGood | boolean | true | Set to false when a rise is bad news, such as costs or errors: the badge turns red when the number goes up. |
Keyboard and screen readers
The rolling digits are hidden from screen readers. They read the label, the final value, and "up" or "down" with the percent. With reduced motion the number changes at once.
Notes
Every colour comes from the --fluid-* variables, except green and red for the change, and the piece is yours to change.
How it is made
One spring carries the number, critically damped, so the digits roll and settle without overshooting the real value. The arrow in the badge is a shape of the engine: up and down are two drawings, and it flows between them. Screen readers get the label, the final value and the change, never the rolling digits.
For your agent
For your agent
Add Stat Counter to my project with the Fluid library. Use StatCounter for the key numbers of my dashboard, with the real values and the previous period to compare. Read my project first. Use my logo, my colours and my font through the --fluid-* variables. Keep 44px touch targets, visible focus and reduced motion. If I have no SVG logo, ask before making one up.