Metric Card
Tile with a label, a headline value that counts up and a signed delta with a direction icon and a stated period. The default tile for a dashboard figure.
How it differs. The baseline tile: one value, one delta, one period. Direction is carried by sign, icon and hidden text together, with no chart and no comparison.
Install
pnpm dlx shadcn@latest add @hazine/metric-cardAdds 1 file, 1 shadcn primitive (card), 1 Hazine item (@hazine/animated-counter), 1 package (lucide-react), and the success token.
First time? Add the registry to components.json
{
"registries": {
"@hazine": "https://api.hazine.dev/r/{name}.json"
}
}Needed once per project. Items resolve each other through the @hazine namespace.
components/hazine/metric-card.tsx, 77 lines
import * as React from "react"
import { TrendingDown, TrendingUp } from "lucide-react"
import { cn } from "@/lib/utils"
import { Card, CardContent } from "@/components/ui/card"
import { AnimatedCounter } from "@/components/hazine/animated-counter"
export interface MetricCardProps extends React.ComponentProps<typeof Card> {
/** Name of the metric. It labels the card for assistive technology. */
label: string
value: number
/** Signed change in percent against the period, for example 12.4 or -3.1. */
delta?: number
/** Baseline the delta is measured against. */
period?: string
locale?: string
/** Passed to Intl.NumberFormat for the value. */
formatOptions?: Intl.NumberFormatOptions
}
export function MetricCard({
label,
value,
delta,
period = "vs last 30 days",
locale = "en-US",
formatOptions,
className,
...props
}: MetricCardProps) {
const labelId = React.useId()
const up = delta !== undefined && delta >= 0
const percent = new Intl.NumberFormat(locale, { maximumFractionDigits: 1 })
return (
<Card
role="group"
aria-labelledby={labelId}
{...props}
data-slot="metric-card"
className={className}
>
<CardContent className="flex flex-col gap-1">
<p id={labelId} className="text-sm text-muted-foreground">
{label}
</p>
<p className="text-2xl font-semibold tracking-tight">
<AnimatedCounter
value={value}
locale={locale}
formatOptions={formatOptions}
/>
</p>
{delta !== undefined && (
<p className="flex flex-wrap items-center gap-1.5 text-sm">
<span
className={cn(
"inline-flex items-center gap-1.5 font-medium tabular-nums",
up ? "text-success" : "text-destructive"
)}
>
{up ? (
<TrendingUp aria-hidden="true" className="size-3.5" />
) : (
<TrendingDown aria-hidden="true" className="size-3.5" />
)}
<span className="sr-only">{up ? "Up" : "Down"}</span>
{up ? "+" : "−"}
{percent.format(Math.abs(delta))}%
</span>
<span className="text-xs text-muted-foreground">{period}</span>
</p>
)}
</CardContent>
</Card>
)
}
The demo in the preview, 42 lines
import { MetricCard } from "@/components/hazine/metric-card"
export default function MetricCardDemo() {
return (
<div className="@container">
<div className="grid gap-4 @md:grid-cols-2">
<MetricCard
label="Collected revenue"
value={48250}
delta={12.4}
formatOptions={{
style: "currency",
currency: "USD",
maximumFractionDigits: 0,
}}
/>
<MetricCard label="Active clients" value={1892} delta={-3.1} />
</div>
</div>
)
}
function MetricCardNoDelta() {
return <MetricCard label="Open invoices" value={37} />
}
function MetricCardOverflow() {
return (
<MetricCard
label="Total value of invoices sent to clients since the workspace was created"
value={1284500000}
delta={248.6}
period="vs the same 30 days one year earlier"
formatOptions={{ style: "currency", currency: "USD" }}
/>
)
}
export const scenarios = {
"no-delta": MetricCardNoDelta,
overflow: MetricCardOverflow,
}
Props6
- labelrequired
- string
- Name of the metric. It labels the card for assistive technology.
- valuerequired
- number
- delta
- number
- Signed change in percent against the period, for example 12.4 or -3.1.
- period
- string = "vs last 30 days"
- Baseline the delta is measured against.
- locale
- string = "en-US"
- formatOptions
- Intl.NumberFormatOptions
- Passed to Intl.NumberFormat for the value.
Also accepts every prop of React.ComponentProps<typeof Card>.
Accessibility
- Pattern
- Landmarks and headings
- Keyboard
- Nothing to operate. The item has no focusable parts.
- Screen reader
A group labelled by the metric name. The delta is read as Up or Down followed by the signed percentage and the period.
- Reduced motion
- The value is shown at once and nothing counts.
- Checked
- Not checked yet. Automated results appear here once CI has run.
Dependencies3
- card
- @hazine/animated-counter
- lucide-react
Filled chips are registry items the CLI adds for you. Outlined chips are npm packages.
Tokens shipped2
- --success
- --success-foreground
Added to your stylesheet in light and dark, unless you already define them.