afv-library/skills/building-webapp-data-visualization/implementation/stat-card.md

Stat Card — Implementation Guide

What is a stat card

A stat card displays a single KPI metric with an optional trend indicator. Used on dashboards to show at-a-glance numbers like "Total Properties: 42 (+10%)".

---

Component interface

interface StatCardProps {
  title: string;
  value: number | string;
  trend?: {
    value: number;
    isPositive: boolean;
  };
  subtitle?: string;
  onClick?: () => void;
}

---

StatCard component

Create at components/StatCard.tsx:

import React from "react";
import { Card } from "@/components/ui/card";
import { TrendingUp, TrendingDown } from "lucide-react";

interface StatCardProps {
  title: string;
  value: number | string;
  trend?: {
    value: number;
    isPositive: boolean;
  };
  subtitle?: string;
  onClick?: () => void;
}

export const StatCard: React.FC<StatCardProps> = ({ title, value, trend, subtitle, onClick }) => {
  return (
    <Card
      className={`p-4 border-gray-200 shadow-sm relative ${
        onClick ? "cursor-pointer hover:shadow-lg transition-shadow" : ""
      }`}
      onClick={onClick}
    >
      <div className="space-y-1">
        <p className="text-sm font-medium text-muted-foreground uppercase tracking-wide">{title}</p>
        <div className="flex items-baseline gap-3">
          <p className="text-4xl font-bold text-primary">{value}</p>
          {trend && (
            <span
              className={`inline-flex items-center gap-1 px-2.5 py-0.5 rounded-full text-sm font-medium ${
                trend.isPositive
                  ? "bg-emerald-100 text-emerald-800"
                  : "bg-pink-100 text-pink-800"
              }`}
            >
              {trend.isPositive ? (
                <TrendingUp className="w-4 h-4" />
              ) : (
                <TrendingDown className="w-4 h-4" />
              )}
              {Math.abs(trend.value)}%
            </span>
          )}
        </div>
        {subtitle && <p className="text-sm text-muted-foreground mt-1">{subtitle}</p>}
      </div>
    </Card>
  );
};

This version uses Lucide icons (TrendingUp/TrendingDown) instead of custom SVGs for portability across projects.

---

Layout: stat card grid

Display stat cards in a responsive grid:

<div className="grid grid-cols-1 md:grid-cols-3 gap-6">
  <StatCard
    title="Total Properties"
    value={metrics.totalProperties}
    trend={{ value: 10, isPositive: true }}
    subtitle="Last month total 38"
  />
  <StatCard
    title="Units Available"
    value={metrics.unitsAvailable}
    trend={{ value: 5, isPositive: false }}
    subtitle="Last month total 12/42"
  />
  <StatCard
    title="Occupied Units"
    value={metrics.occupiedUnits}
    trend={{ value: 8, isPositive: true }}
    subtitle="Last month total 27"
  />
</div>

---

Computing trend values

Calculate trends from current vs previous period:

const trends = useMemo(() => {
  const previousTotal = metrics.totalProperties - Math.round(metrics.totalProperties * 0.1);
  const trendPercent = previousTotal > 0
    ? Math.round(((metrics.totalProperties - previousTotal) / previousTotal) * 100)
    : 0;

  return {
    value: Math.abs(trendPercent),
    isPositive: trendPercent >= 0,
  };
}, [metrics]);

---

Trend badge color conventions

Trend	Background	Text	Meaning
Positive (up)	bg-emerald-100	text-emerald-800	Growth, improvement
Negative (down)	bg-pink-100	text-pink-800	Decline, concern
Neutral	bg-gray-100	text-gray-600	No change

---

Accessibility

• Card uses cursor-pointer and hover:shadow-lg only when onClick is provided.
• Trend icons have implicit meaning from color + direction icon.
• Stat values use large, bold text for visibility.
• Title uses uppercase tracking-wide for visual hierarchy without heading tags (appropriate in a card grid).