Stat Card
Compact admin dashboard metric card with label, value, delta, trend, and footer slots. Built with CSS Modules, container queries, and accessible delta announcements — copy it into your project and own it completely.
npx visor add stat-cardBasic
Total Revenue
$48,120
With Delta (Up)
Total Revenue
$48,120
With Delta (Down)
Churn Rate
3.2%
With Delta (Flat)
Signups
412
With Trend
Sessions
2,340
With Footer
Active Users
892
Variants
Variants control visual emphasis. Pair with any size.
Default
1,204
Highlight
$48,120
Sizes
Dimensional density. md is the dashboard default; sm is for dense rows of compact cards where multiple metrics need to share a tight row.
Active Users
892
Sessions
2,340
Signups
412
Bounce
28%
Revenue
$12k
Installation
npx visor add stat-cardThis copies two files into your project:
components/ui/stat-card/stat-card.tsx— the componentcomponents/ui/stat-card/stat-card.module.css— the styles
Usage
import { StatCard } from '@/components/ui/stat-card/stat-card';
export default function Example() {
return (
<StatCard
label="Total Revenue"
value="$48,120"
delta={{ value: '+12.4%', direction: 'up', label: 'vs last month' }}
/>
);
}API Reference
StatCardProps
| Prop | Type | Default | Description |
|---|---|---|---|
label* | React.ReactNode | — | Small uppercase label describing the metric. |
value* | React.ReactNode | — | Prominent metric value rendered in a large display size. |
delta | StatCardDelta | — | Change indicator with value, direction ("up" | "down" | "flat"), and optional context label. Direction is announced to screen readers. |
trend | React.ReactNode | — | Slot for a sparkline, chart, or icon rendered next to the label. Marked aria-hidden by default. |
footer | React.ReactNode | — | Sublabel or link rendered beneath the value. |
variant | 'default' | 'highlight' | 'default' | Visual emphasis. Highlight adds an accent-tinted surface, border, and glow. |
size | 'sm' | 'md' | 'md' | Dimensional density. Use sm for dense rows of compact cards; md is the default dashboard size. |
as | 'article' | 'section' | 'div' | 'article' | Root element tag. Defaults to article for landmark semantics. |
className | string | — | Additional CSS class names to merge onto the root element. |
...props | React.HTMLAttributes<HTMLElement> | — | All standard HTML attributes are forwarded to the root. |
The component also accepts all standard HTML attributes for the root element (defaults to <article>).
StatCardDelta
| Field | Type | Description |
|---|---|---|
value | React.ReactNode | Display value, e.g. "+12.4%" or "-$2.1K". |
direction | 'up' | 'down' | 'flat' | Semantic direction — drives color and glyph. |
label | string (optional) | Context label (e.g. "vs last month"). Visible and announced. |
Accessibility
Color alone is never sufficient to convey the direction of a change. StatCard always announces the direction word (up, down, or flat) to screen readers via visually-hidden text alongside the visible glyph and delta value. The glyph itself is marked aria-hidden so assistive tech hears a clean sentence like "up 12.4% vs last month".
The root element defaults to <article>, giving screen reader users a landmark they can navigate to. Use the as prop to override this when embedding inside another landmark.
Source Files
After running npx visor add stat-card, you'll have:
stat-card.tsx
A forwardRef component using CVA for variant selection and CSS Modules for layout. The root element is configurable via the as prop.
stat-card.module.css
All styles use CSS custom properties from @loworbitstudio/visor-core, so the card automatically adapts to your active theme. The wrapper uses container-type: inline-size so the header row collapses on very narrow containers instead of overflowing. Transitions are wrapped in a prefers-reduced-motion guard.
Customization
After copying the component, you own it completely. Common customizations:
- Replace the Unicode arrow glyphs with Phosphor icons (
ArrowUp,ArrowDown,Minus). - Add a
loadingstate that renders a skeleton value. - Extend variants with a
subtletreatment for secondary dashboards. - Swap the
<article>root for a<button>when the whole card should be clickable.
Score Indicator
Compact circular ring visualization for percentage or ratio metrics — health score, uptime, engagement, capacity. Auto-toned color mapping derived from the value/max ratio.
Stat Hero
Hero-scale animated metric banner for flagship KPI display. A 35/65 grid banner with a large headline value on the left and a full-height animated trendline on the right — copy it into your project and own it completely.