@mshafiqyajid/react-stat
Headless hook + styled card for statistic displays. Smooth count-up animation, trend direction (up/down/neutral), loading skeleton, prefix/suffix slots, primary tone.
Playground #
Total Users
12.5%vs last month
Revenue
8.2%vs last month
Conversion
1.2%vs last month
Total Users
12.5%vs last month
Props
TSX
import { StatStyled } from "@mshafiqyajid/react-stat/styled";
import "@mshafiqyajid/react-stat/styles.css";
<StatStyled />Install #
npm install @mshafiqyajid/react-statQuick start #
import { StatStyled } from "@mshafiqyajid/react-stat/styled";
import "@mshafiqyajid/react-stat/styles.css";
<StatStyled
value={12847}
label="Total Users"
trend={12.5}
trendLabel="vs last month"
/>With prefix and suffix #
<StatStyled value={98420} label="Revenue" trend={8.2} prefix="$" />
<StatStyled value={3.4} label="Conversion" trend={-1.2} suffix="%" />Derived trend #
Pass previousValue instead of trend and the component derives the percentage change automatically.
<StatStyled
value={1250}
label="Sign-ups"
previousValue={1000}
trendLabel="vs last week"
/>Loading skeleton #
<StatStyled value={0} label="Revenue" loading={true} />Headless #
import { useStat } from "@mshafiqyajid/react-stat";
const { rootProps, valueProps, animatedValue, trendDirection } = useStat({
value: 12847,
label: "Total Users",
trend: 12.5,
countUp: true,
countUpDuration: 1200,
});
return (
<figure {...rootProps}>
<p>Total Users</p>
<span {...valueProps}>{animatedValue.toLocaleString()}</span>
{trendDirection === "up" && <span aria-label="trending up">↑ 12.5%</span>}
</figure>
);API #
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | number | — | The statistic value to display |
| label | string | — | Descriptive label above the value |
| previousValue | number | — | Previous value — derives trend automatically |
| trend | number | — | Explicit trend percentage (overrides derived) |
| trendLabel | string | — | Contextual label beside trend (e.g. "vs last month") |
| trendFormat | "percent" | "absolute" | "percent" | How trend magnitude is displayed |
| prefix | ReactNode | — | Content before value (e.g. "$") |
| suffix | ReactNode | — | Content after value (e.g. "%") |
| icon | ReactNode | — | Icon displayed beside the label |
| size | "sm" | "md" | "lg" | "md" | Card size |
| tone | "neutral" | "primary" | "neutral" | Color tone |
| countUp | boolean | true | Animate value counting up on mount |
| countUpDuration | number | 1000 | Count-up animation duration (ms) |
| countUpDelay | number | 0 | Delay before animation starts (ms) |
| loading | boolean | false | Show pulsing skeleton placeholder |
| className | string | — | Extra class on the root element |
| style | CSSProperties | — | Inline style override |