# Metric

> A measurement with its unit, a meter against its limit and a status that pairs an icon with a word.

Category: Data display · Atomic level: molecule
Page: https://ui.dtheo.dev/docs/components/metric

## Install

```bash
npx dtheo@latest add metric
# or, with the shadcn CLI
npx shadcn@latest add https://ui.dtheo.dev/r/metric.json
```

Dependencies: clsx, tailwind-merge, lucide-react. Registry dependencies: utils.

## Exports

`MetricGroup`, `Metric`

## Use it for

- Acceptance checks for a test run
- KPI rows on a dashboard

## Reach for something else

- Values without a limit or comparison: a plain table row reads faster
- More than 6 values in a row: use a Table

## Accessibility

- Passing values stay neutral; only warnings and failures use color, and always with a word.

## Examples

### metric

```tsx
import { Metric, MetricGroup } from '@/components/ui/metric';

// Acceptance checks for R-0412 "High-gain step" on Bench 3. Failing and near-limit checks lead.
// `progress` and `limit` are positions on each meter (0 to 1); each meter spans 0 to 125 % of its limit.
const on = (value: number, limit: number) => ({ progress: value / (limit * 1.25), limit: 0.8 });

export default function MetricExample() {
  return (
    // Five checks wrap unevenly in narrow containers, so the failing check takes the full first row there.
    <div className="@container w-full">
      <MetricGroup className="grid-cols-2 @xl:grid-cols-3 @2xl:grid-cols-5">
        <Metric
          className="col-span-2 @2xl:col-span-1"
          label="Overshoot"
          value="17.6"
          unit="%"
          status="fail"
          {...on(17.6, 10)}
          limitLabel="Limit 10 %"
        />
        <Metric
          label="Settling time"
          value="186"
          unit="ms"
          status="warn"
          {...on(186, 200)}
          limitLabel="Limit 200 ms"
        />
        <Metric
          label="Phase current"
          value="31.2"
          unit="A"
          status="pass"
          {...on(31.2, 40)}
          limitLabel="Limit 40 A"
        />
        <Metric
          label="Winding temp."
          hint="Winding temperature"
          value="71.2"
          unit="°C"
          status="pass"
          {...on(71.2, 90)}
          limitLabel="Limit 90 °C"
        />
        <Metric
          label="Steady-state error"
          value="0.4"
          unit="%"
          status="pass"
          {...on(0.4, 2)}
          limitLabel="Limit 2 %"
        />
      </MetricGroup>
    </div>
  );
}
```

## Used in

- Run review (page): https://ui.dtheo.dev/examples/run-review
- Motor map (page): https://ui.dtheo.dev/examples/motor-map
- Loop tuning (page): https://ui.dtheo.dev/examples/tuning
- Lab assistant (page): https://ui.dtheo.dev/examples/assistant
- Home page (page): https://ui.dtheo.dev/
