# Meter (goodtabs UI)

A reading against low, high and optimum, with the real meter role.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/meter.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/meter`

## Usage

```tsx
import { Meter } from "@/components/ui/meter"

<Meter label="Contrast score" value={82} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | `string` |  | What is measured. |
| value | `number` |  | The reading. |
| min | `number` | `0` | Bottom of the range. |
| max | `number` | `100` | Top of the range. |
| low | `number` | `25% of the range` | Values below this are low. |
| high | `number` | `75% of the range` | Values above this are high. |
| optimum | `number` | `max` | The best value. Decides which zone is good. |
| format | `(value: number) => string` |  | Formats the reading on the right. |

## When to use

- A score or measurement with a good range, such as a performance metric
- Capacity or quota where the middle is healthy

## When not to use

- Work that moves toward done: use progress-bar
- Several values over time: use a chart

## Notes for agents

- Status follows the HTML meter rules: the zone of the optimum decides which end is good
- Good, fair and poor change the fill opacity and are also written as text; there is no red or green
- The format prop is a function, so a client parent must be a client component
- Server component; all state comes from props

## The maths

- Each tick sits at (v - min) / (max - min). With low 25 and high 75 on 0 to 100 they land at 25 and 75 percent.
- Zone of a value v is low if v < low, high if v > high, else middle. Status is good when v and the optimum share a zone, poor when both differ from the middle, fair otherwise.

Docs: https://ui.goodtabs.co/components/meter