# Stat & Metric

> A key number with its trend: Metric card for dashboards, Metric item for compact tiles, and the gauge for a value against a known range.

Source: https://ritla.app/ui/metric

## Installation

Installing from the registry is coming soon. Until then, these are the commands you will run.

```bash
npx ritla add metric
```

With the shadcn CLI instead:

```bash
npx shadcn@latest add @ritla/metric
```

Dependencies: `@phosphor-icons/react`

## Usage

```tsx
import { MetricItem, MetricCard, MetricBars } from "@/components/ui/metric";

<MetricItem label="Transfers this month" value="1,284" trend={{ value: "12%", direction: "up" }} />
<MetricCard title="Card spending" value="1,240" trend={{ value: "25%", direction: "up" }} period="vs last month" chart={<MetricBars data={[25, 50, 100, 75, 50, 10]} />} />
```

## Examples

### Metric card

Bars beside the number, a progress bar above it, or a small gauge. The bars keep running left to right in Arabic; progress fills from the inline start.

Live preview: https://ritla.app/_kanz/preview/ltr/metric-cards

### Metric item types

`type` picks Figma's layout: an icon in a square, a mini chart beside or under the number, or a title band. The footer is a settings button and a View report button.

Live preview: https://ritla.app/_kanz/preview/ltr/metric-types

### Gauge

One value against a known range with good and bad zones. `scale` says which end is good. In Arabic the dial mirrors, so the scale runs from the right.

Live preview: https://ritla.app/_kanz/preview/ltr/metric-gauge

### Color follows meaning

More failed payments is bad news: the arrow points up, and the tag and the line are red (`tone: "negative"`).

Live preview: https://ritla.app/_kanz/preview/ltr/metric-meaning

## API reference

### `MetricItem`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `"simple" \| "icon-01" … "icon-04" \| "chart-01" … "chart-04"` | `"simple"` | Figma's Type: the tile's layout. |
| `label` | `ReactNode` | None | The metric and its period (“Views in 24 hours”). |
| `value` | `ReactNode` | None | The number, formatted with its unit. |
| `trend` | `{ value, direction: "up" \| "down", tone? }` | None | The change. `tone` says whether it is good news (green) or bad (red), by meaning, not direction. |
| `period` | `ReactNode` | None | The comparison after the trend (“vs last month”). |
| `icon` | `IconComponent` | None | The holder's icon in the Icon types and Chart 02. |
| `iconColor` | `"brand" \| "green" \| "red" \| "amber" \| "gray"` | `"brand"` | The circle's color in Icon 01 and 02. |
| `chart` | `number[]` | None | The mini chart's values in time order, oldest first. |
| `chartLabel` | `string` | None | A text summary of the chart; without one it is hidden from screen readers. |
| `menu` | `ReactNode` | None | An icon button opening a Menu, at the top inline end. |
| `footer` | `ReactNode` | None | Figma's Actions: a link or buttons in the footer. |

### `MetricCard`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` | None | The metric and its period. |
| `value / trend / period` | `…` | None | As in `MetricItem`; the trend is a tag here. |
| `type` | `"bar-chart" \| "progress"` | `"bar-chart"` | Figma's Type: the chart beside the number, or a progress bar above it. |
| `chart` | `ReactNode` | None | `MetricBars`, `MetricProgress` or `MetricGauge size="sm"`. |
| `menu / footer` | `ReactNode` | None | The menu button, and the footer (usually a See details link). |

### `MetricBars / MetricSparkline / MetricProgress`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `number[]` | None | The values in time order (two to six bars). |
| `highlight` | `number` | None | The strong bar; the highest by default. |
| `size` | `"sm" \| "md" \| "lg"` | `"lg"` | The bars' size: 12, 16 or 24px wide. |
| `value / max / label` | `number, number, string` | None | In `MetricProgress`: progress toward a goal, a named meter. |

### `MetricGauge`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value / min / max` | `number` | None | The value and its known range. |
| `scale` | `"high-is-good" \| "low-is-good"` | `"high-is-good"` | Figma's Scale: which end is good, which orders the red and green zones. |
| `size` | `"md" \| "sm"` | `"md"` | md with the value, label and scale ends; sm the dial alone, inside a card. |
| `label` | `string` | None | What it measures, printed under the value; the meter's name. |
| `valueText / minText / maxText` | `ReactNode` | None | The value and the scale ends as printed. |

## Accessibility

Keyboard (keys as in left-to-right; arrows swap in right-to-left):

- `Tab`: Only to the menu button and the footer's link and buttons; numbers and charts aren't interactive.

ARIA:

- The trend is read in words (“Up 25%”) and the arrow is hidden, so color and the arrow are never the only signal.
- Mini charts are hidden from screen readers because the tile says the number; pass `label` to give one a summary.
- The gauge and the progress bar are `meter`s with a minimum, maximum and value.
- The menu button names its metric (“Transfers this month options”).

## Arabic and RTL notes

Mirrors:

- The label, value and trend sit on the right; the menu on the left.
- The gauge's dial mirrors and runs from the right.
- The progress bar fills from the inline start, the right.

Does not mirror:

- Mini charts and bars: time runs left to right.
- Trend arrows.
- Numbers and percentages read left to right.

Numerals: Numbers are as you pass them; format them with `formatNumber` so they follow the product's numerals, the same way on every tile.

Arabic typography: Value `heading-28` Semibold in the item and `heading-42` Medium in the card; label `body-14` or `body-16`; trend `body-14` Medium.

Mixed-direction text: The value and percentage are isolated LTR, so the percent sign and separators don't reorder inside Arabic text.