# StatsCard

## Overview

A pre-built KPI (Key Performance Indicator) card for dashboard overview pages. Renders a metric title, a large value, an optional trend indicator with automatic up/down/neutral icon, and an optional icon.

Built on top of `<Card>`. Use it for dashboard stat widgets where a consistent metric display is needed.

---

## When to Use

- Dashboard overview pages to show summary metrics (revenue, users, conversion)
- KPI widgets that need to show value + trend direction

## When NOT to Use

- For arbitrary content — use `<Card>` directly.
- When you need to heavily customize layout — compose from `<Card>` primitives instead.

---

## Props

| Prop          | Type                                | Required | Description                                                                                               |
| ------------- | ----------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `title`       | `string`                            | **Yes**  | Metric label (short)                                                                                      |
| `value`       | `string \| number`                  | **Yes**  | The displayed metric value                                                                                |
| `description` | `string`                            | No       | Additional supplementary text below the value                                                             |
| `trend`       | `{ value: number; label?: string }` | No       | Trend object. `value` is a number (positive = up, negative = down). `label` overrides `description` text. |
| `icon`        | `ReactNode`                         | No       | Icon from `lucide-react`                                                                                  |
| `iconColor`   | `string`                            | No       | Tailwind class for the icon text/foreground color (defaults to `text-muted-foreground`)                   |
| `iconBg`      | `string`                            | No       | Tailwind class for the icon background color (defaults to `bg-muted`)                                     |
| `className`   | `string`                            | No       | Additional CSS classes |

### trend

The `trend` prop controls the automatic trend icon and color:

- `trend.value > 0` → shows `TrendingUp` icon in green
- `trend.value < 0` → shows `TrendingDown` icon in red (destructive)
- `trend.value === 0` → shows `Minus` icon in muted

The numeric value is displayed as an absolute percentage: `Math.abs(trend.value)%`.

---

## Examples

### Basic KPI Card

```tsx
import { StatsCard } from 'xertica-ui/ui';
import { DollarSign } from 'lucide-react';

<StatsCard
  title="Total Revenue"
  value="$45,231.89"
  trend={{ value: 20.1, label: 'from last month' }}
  icon={<DollarSign className="size-5" />}
/>;
```

### Custom Icon Colors

```tsx
import { StatsCard } from 'xertica-ui/ui';
import { Users } from 'lucide-react';

<StatsCard
  title="Active Users"
  value="2,350"
  trend={{ value: 8.2, label: 'new this week' }}
  icon={<Users className="size-5" />}
  iconBg="bg-primary/10"
  iconColor="text-primary"
/>;
```

### Negative Trend

```tsx
<StatsCard
  title="Churn Rate"
  value="3.2%"
  trend={{ value: -0.8, label: 'vs last quarter' }}
  icon={<TrendingDown className="size-5" />}
/>
```

### Stats Grid (4 columns)

```tsx
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
  <StatsCard
    title="Revenue"
    value="$45,231"
    trend={{ value: 20.1, label: 'from last month' }}
    icon={<DollarSign className="size-5" />}
  />
  <StatsCard
    title="Active Users"
    value="2,350"
    trend={{ value: 8.2, label: 'new this week' }}
    icon={<Users className="size-5" />}
  />
  <StatsCard
    title="Conversion"
    value="3.6%"
    trend={{ value: -0.4, label: 'vs last month' }}
    icon={<Activity className="size-5" />}
  />
  <StatsCard
    title="Avg. Ticket"
    value="$89.40"
    description="All time average"
    icon={<ShoppingCart className="size-5" />}
  />
</div>
```

---

## AI Rules

- `trend.value` is a **numeric percentage** (e.g., `20.1` for +20.1%) — the component displays `Math.abs(value)%` automatically.
- Do NOT pre-format the trend value as a string — pass the raw number.
- `value` IS pre-formatted as a display string: `"$45,231"`, `"3.6%"`, `"2,350"`.
- Icons render inside a rounded background. By default, background is `bg-muted` and color is `text-muted-foreground`, but they can be customized using `iconBg` and `iconColor` props. Use `size-5` for the icon.
- Always use in a 4-column responsive grid for dashboard overviews.
- `trend.label` takes precedence over `description` for below-value text.

---

## Related Components

- [`Card`](./card.md) — The underlying primitive
- [Dashboard Pattern](../patterns/dashboard.md) — Standard usage context