# KPI tile

> Compact tinted counters and neutral dashboard cards for one labelled metric.

- Group: Core
- Status: stable
- Aliases: kpi, stat
- HTML page: https://design.ipmnx.com/components/kpi-tile/
- Spec: https://design.ipmnx.com/design/#nx-kpi-tile

## Preview

**Jobs today**

```html
<div class="nx-kpi">
  <div class="nx-kpi__num">14</div>
  <div class="nx-kpi__lbl">Jobs today</div>
</div>
```

```tsx
<NxKpiTile value="14" label="Jobs today" />
```

## Variants

### Dashboard card

One linked metric, with a decorative calendar icon and factual context.

```html
<a class="nx-kpi nx-kpi--card nx-kpi--link" href="#kpi-tile">
  <dl class="nx-kpi__metric">
    <dt class="nx-kpi__heading">
      <span class="nx-kpi__lbl">Jobs today</span>
      <span class="nx-kpi__icon" aria-hidden="true">
        <svg width="18" height="18" viewBox="0 0 24 24" fill="none"
            stroke="currentColor" stroke-width="2">
          <rect x="3" y="5" width="18" height="16" rx="2"/>
          <path d="M16 3v4M8 3v4M3 11h18"/>
        </svg>
      </span>
    </dt>
    <dd class="nx-kpi__num"><bdi>14</bdi></dd>
  </dl>
  <p class="nx-kpi__description">Scheduled for today</p>
</a>
```

```tsx
const icon = <NxNavIcon name="calendar" />;
<NxKpiTile
  variant="card"
  value="14"
  label="Jobs today"
  icon={icon}
  description="Scheduled for today"
  href="#kpi-tile"
/>
```

## API

### React props (NxKit)

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `value` | `ReactNode` |   | yes | The complete metric; localized numbers/currencies are supplied by the host. |
| `label` | `ReactNode` |   | yes | Visible metric label. |
| `variant` | `"compact"\|"card"` | `"compact"` |   | Compact tinted counter or full neutral dashboard card. |
| `icon` | `ReactNode` | `undefined` |   | Card only: decorative product-tinted icon. |
| `description` | `ReactNode` | `undefined` |   | Card only: factual unit, period or supporting context. |
| `href` | `string` | `undefined` |   | Card only: turns the entire card into one link. |
| `linkComponent` | `React.ElementType` | `"a"` |   | Card only: framework/locale link; supply from a client component when the router is client-owned. |
| `className` | `string` | `""` |   | Card only: optional layout class. |

### Classes

| Class | Description |
| --- | --- |
| `.nx-kpi` | Compact tile: accent-50 fill, 12px radius |
| `.nx-kpi--card` | Neutral bordered dashboard card, semantic label/value and tabular numerals |
| `.nx-kpi--link` | Whole-card link with hover tint and visible keyboard focus |
| `.nx-stat-grid` | Responsive grid that fits available content width |
| `.nx-kpi__num` | Metric value; ink in cards, accent-700 in compact counters |
| `.nx-kpi__lbl` | Visible secondary label |
| `.nx-kpi__icon` | Small decorative product-accent icon |
| `.nx-kpi__description` | Optional supporting context |

## Accessibility

- Dashboard cards associate the visible label/value in a definition list and isolate localized values with bdi. Icons are decorative. Linked cards use native anchor semantics and a visible focus outline; static cards are not tab stops.
- Keep slots free of nested controls. Never invent growth or trend data. The card grid wraps to available width, and long values remain readable.

## Do / Don't

- Do: Use one labelled metric per card; add a real unit or period when needed.
- Don't use random per-metric colors or fabricate trend indicators.

## Related

- [Card](https://design.ipmnx.com/components/card.md)
- [Badge](https://design.ipmnx.com/components/badge.md)

---

Source: registry.js (NX Design System)
