# Meter

A gauge for a value within a known range.

Source: [meter.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/meter.tsx)

```tsx
import { Meter, MeterLabel, MeterValue } from "@/components/ui/meter";

export default function MeterBasic() {
  return (
    <Meter value={64} className="w-full max-w-sm">
      <MeterLabel>Build minutes</MeterLabel>
      <MeterValue />
    </Meter>
  );
}
```

## Installation

Add the registry, once per project:

```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```

Then add the component:

```bash
npx shadcn@latest add @jarvis/meter
```

## Usage

```tsx
import { Meter, MeterLabel, MeterValue } from "@/components/ui/meter";

export function BuildMinutes() {
  return (
    <Meter value={64}>
      <MeterLabel>Build minutes</MeterLabel>
      <MeterValue />
    </Meter>
  );
}
```

Use a meter for a measurement within a range, such as storage used, and
[Progress](https://ui.jarv.is/components/progress.md) for a task that's underway.

## Composition

- `Meter`
  - `MeterLabel`
  - `MeterValue`

## Examples

### Formatted value

`MeterValue` shows a percentage by default. Pass a function as its children to format it yourself.
Set `max` when the range isn't 0 to 100.

```tsx
import { Meter, MeterLabel, MeterValue } from "@/components/ui/meter";

export default function MeterFormattedValue() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-6">
      <Meter value={2.4} max={10}>
        <MeterLabel>Storage</MeterLabel>
        <MeterValue>{(_, value) => `${value.toFixed(1)} of 10 GB`}</MeterValue>
      </Meter>
      <Meter value={17} max={25}>
        <MeterLabel>Seats</MeterLabel>
        <MeterValue>{(_, value) => `${value} of 25`}</MeterValue>
      </Meter>
    </div>
  );
}
```

### Colors

Recolor the indicator by targeting its `data-slot` from the root.

```tsx
import { Meter, MeterLabel, MeterValue } from "@/components/ui/meter";

export default function MeterColors() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-6">
      <Meter value={78} className="**:data-[slot=meter-indicator]:bg-warning">
        <MeterLabel>Build minutes</MeterLabel>
        <MeterValue />
      </Meter>
      <Meter value={94} className="**:data-[slot=meter-indicator]:bg-destructive">
        <MeterLabel>Bandwidth</MeterLabel>
        <MeterValue />
      </Meter>
      <Meter value={52} className="**:data-[slot=meter-indicator]:bg-brand">
        <MeterLabel>Requests</MeterLabel>
        <MeterValue />
      </Meter>
    </div>
  );
}
```

## Props

| Part | Extends |
| --- | --- |
| `Meter` | [`Meter.Root`](https://base-ui.com/react/components/meter#root) |
| `MeterTrack` | [`Meter.Track`](https://base-ui.com/react/components/meter#track) |
| `MeterIndicator` | [`Meter.Indicator`](https://base-ui.com/react/components/meter#indicator) |
| `MeterLabel` | [`Meter.Label`](https://base-ui.com/react/components/meter#label) |
| `MeterValue` | [`Meter.Value`](https://base-ui.com/react/components/meter#value) |

The tables leave out `className`, `style` and `render`. Parts built on Base UI take them as its [styling](https://base-ui.com/react/handbook/styling) and [composition](https://base-ui.com/react/handbook/composition) guides describe.

### Meter

| Prop                | Type                                                  | Description                                                                                                                                 |
| ------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `aria-valuetext?`   | `string`                                              | A string value that provides a user-friendly name for `aria-valuenow`, the current value of the meter.                                      |
| `format?`           | `Intl.NumberFormatOptions`                            | Options to format the value.                                                                                                                |
| `getAriaValueText?` | `((formattedValue: string, value: number) => string)` | A function that returns a string value that provides a human-readable text alternative for `aria-valuenow`, the current value of the meter. |
| `locale?`           | `Intl.LocalesArgument`                                | The locale used by `Intl.NumberFormat` when formatting the value. Defaults to the user's runtime locale.                                    |
| `max?`              | `number`                                              | The maximum value Default: `100`                                                                                                            |
| `min?`              | `number`                                              | The minimum value Default: `0`                                                                                                              |
| `value`             | `number`                                              | The current value.                                                                                                                          |

### MeterValue

| Prop        | Type                                                                   | Description |
| ----------- | ---------------------------------------------------------------------- | ----------- |
| `children?` | `((formattedValue: string, value: number) => React.ReactNode) \| null` |             |