# Meter

> The headless Meter of @audio-ui/react: its parts, what each renders and owns, and their props.

```bash
npm install @audio-ui/react
```

```ts
import { Meter } from "@audio-ui/react/meter";
```

| Export | Kind | What it is |
| --- | --- | --- |
| `Meter.Channel` | function | One channel of the meter, a `role="meter"`: name it with `aria-label` or a `Meter.Label`. |
| `Meter.Channels` | function | Renders one child per channel. |
| `Meter.Indicator` | function | The lit part of the channel, scaled to the level. |
| `Meter.Label` | function | Accessible label of the channel it is in. |
| `Meter.Mark` | function | A graduation of the level scale at `value`, such as -18 dB: placed along the meter's length from its minimum, upward for a vertical meter and rightward for a horizontal one. |
| `Meter.Peak` | function | The peak-hold mark, positioned at the channel's peak level; hidden while the channel has none. |
| `Meter.Root` | function | Groups the channels of a level meter. |
| `Meter.Track` | function | The full range of a channel, behind the indicator. |
| `Meter.Value` | function | The channel's formatted level (`format`/`locale` on Root). |

## Anatomy

Import the primitive and assemble its parts.

```tsx
import { Meter } from "@audio-ui/react";

<Meter.Root>
  <Meter.Channels>
    {(index) => (
      <Meter.Channel index={index}>
        <Meter.Indicator />
        <Meter.Peak />
      </Meter.Channel>
    )}
  </Meter.Channels>
</Meter.Root>
```

## API reference

### Root

Groups the channels of a level meter. Levels come either from `value` (and `peak`) as React props, or from a live `source`: with a source the meter writes each frame straight to the DOM, so a signal updating 60 times a second never re-renders React. Renders a `<div>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `clipThreshold` | `number` | `0` | Level at or above which a channel is clipping. |
| `format` | `Intl.NumberFormatOptions` |  | Formats each level for `Meter.Value` and the channels' `aria-valuetext`. Defaults to one decimal. |
| `locale` | `Intl.LocalesArgument` |  |  |
| `max` | `number` | `6` |  |
| `min` | `number` | `-60` |  |
| `orientation` | `Orientation` | `"vertical"` |  |
| `peak` | `readonly number[]` |  | Peak-hold level per channel. Timing and decay live outside the primitive. |
| `scale` | `"linear" \| "iec" \| (level: number) => number` | `"linear"` | How levels are spread along the length: evenly, as digital peak meters do with more room at the top (`"iec"`), or by your own increasing curve. |
| `warnThreshold` | `number` |  | Level at or above which a channel is in its warning zone, below the clip threshold: `data-warning`. Unset, there is no warning zone. |
| `source` | `Source` |  | A live signal painted outside React; takes precedence over `value` and `peak`. |
| `value` | `readonly number[]` |  | Level per channel; the array length is the channel count. |

### Channels

Renders one child per channel.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `(index: number, channelCount: number) => React.ReactNode` |  |  |

### Channel

One channel of the meter, a `role="meter"`: name it with `aria-label` or a `Meter.Label`. Carries `data-clipping` at or above the clip threshold. Renders a `<div>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `getAriaValueText` | `(formattedValue: string, value: number, index: number) => string` |  | Returns the channel's `aria-valuetext`, e.g. `"-6 dB"`. Defaults to the formatted level. |
| `index` | `number` |  | Index of the channel in the levels. |

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-clipping` | Whether the level is at or above the clip threshold. |

### Indicator

The lit part of the channel, scaled to the level. Renders a `<div>` element.

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-clipping` | Whether the level is at or above the clip threshold. |

### Peak

The peak-hold mark, positioned at the channel's peak level; hidden while the channel has none. Renders a `<div>` element.

**Data attributes**

| Attribute | Description |
| --- | --- |
| `data-clipping` | Whether the level is at or above the clip threshold. |

### Value

The channel's formatted level (`format`/`locale` on Root). With a live `source` only the default text is kept current, not a `children` function. Renders a `<span>` element.

### Mark

A graduation of the level scale at `value`, such as -18 dB: placed along the meter's length from its minimum, upward for a vertical meter and rightward for a horizontal one. Sits directly in `Root`, beside the channels. Decorative: each channel announces its own level. Renders a `<div>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` |  | Where the mark sits, between `min` and `max`. |

## Styled

The registry's styled Meter, its usage and interaction: [Meter](/docs/components/base/meter).