---
title: "StatCard"
description: "A KPI card: label, tabular value, semantic delta, context and an optional sparkline. Color reinforces the reading, but the sign and the text explain the change."
kind: component
id: C-039
registry: "stat-card"
docs: "https://koten.codehive.com.co/components/stat-card"
markdown: "https://koten.codehive.com.co/md/components/stat-card.md"
install: "npx shadcn@latest add https://koten.codehive.com.co/r/stat-card.json"
language: en
---

# StatCard · 指標

> Component C-039 in the Koten UI catalog.

A KPI card: label, tabular value, semantic delta, context and an optional sparkline. Color reinforces the reading, but the sign and the text explain the change.

> Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031).

## Install

Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project.

```bash
# Node
npx shadcn@latest add https://koten.codehive.com.co/r/stat-card.json

# Bun
bunx shadcn@latest add https://koten.codehive.com.co/r/stat-card.json
```

## Files

- `@/components/ui/stat-card.tsx`
- `@/lib/koten/cn.ts`
- `@/lib/koten/format.ts`
- `@/lib/koten/intl.ts`
- `@/lib/koten/labels.ts`
- `@/lib/koten/provider.tsx`

## Examples

### Four KPIs

Label, value, delta, meta and sparkline; color reinforces and text explains.

```tsx
<div className="grid gap-[var(--koten-gap)] sm:grid-cols-2 xl:grid-cols-4">
  <StatCard
    label="Pedidos hoy"
    value="128"
    delta={{ value: "+12 %", tone: "success" }}
    meta="vs. ayer"
    sparkline={<Sparkline data={[18, 24, 21, 32, 28, 38, 42]} label="Tendencia de pedidos" />}
  />
  <StatCard
    label="Pendientes"
    value="9"
    delta={{ value: "-3", tone: "success" }}
    meta="Requieren preparación"
    sparkline={<Sparkline data={[12, 10, 9, 11, 8, 9, 7]} label="Tendencia de pendientes" />}
  />
  <StatCard
    label="Ingresos"
    value={formatCurrency(1284000, { maximumFractionDigits: 0 })}
    delta={{ value: "+8 %", tone: "success" }}
    meta="Últimos 7 días"
    sparkline={<Sparkline data={[8, 9, 8, 11, 10, 12, 13]} label="Tendencia de ingresos" />}
  />
  <StatCard
    label="Stock bajo"
    value="4"
    delta={{ value: "+1", tone: "danger" }}
    meta="SKUs bajo mínimo"
    sparkline={<Sparkline data={[2, 2, 3, 2, 3, 3, 4]} label="Tendencia de stock bajo" />}
  />
</div>
```

## Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `label` | `ReactNode` | `—` | Short KPI label; rendered small in the faint color. |
| `value` | `ReactNode` | `—` | Main value; uses tabular-nums and leading-none to align figures. |
| `delta` | `{ value: ReactNode; tone?: "success" \| "danger" \| "neutral" }` | `—` | The tone only reinforces; the sign and text must explain the change. |
| `meta` | `ReactNode` | `—` | Context below the value, such as the comparison period. |
| `sparkline` | `ReactNode` | `—` | Rendered in the primary color; usually a <Sparkline />. |
| `className` | `string` | `—` | Container classes; border, background and padding come from tokens. |

## Accessibility

- The value and label are real text; the delta does not rely on color alone and also carries a sign and text.
- The sparkline needs an aria-label; the main value remains available as text.
- The card is not interactive; if it wraps a link, focus goes to the link, not the container.

## Sources

- Catalog page: https://koten.codehive.com.co/components/stat-card
- Markdown: https://koten.codehive.com.co/md/components/stat-card.md
- Repository: https://github.com/codehive-colombia/koten