---
title: Meter
description: Meters display a scalar value within a known range (storage used, quiz score, or battery level) without implying user input.
---

import { meta as MeterMeta, Default } from '@/content/stories/meter';
import Canvas from '@/components/component-docs/canvas';
import Demo from '@/components/component-docs/demo';

export const config = {
	dependencies: {
		components: [Canvas, Demo],
		scripts: [
			'../../../components/component-docs/demo.script.tsx',
			'../../../components/component-docs/canvas.script.tsx',
			'../../../components/component-docs/controls.script.tsx',
		],
	},
};


# Meter

<p class="docs-lede">Meters display a scalar value within a known range (storage used, quiz score, or battery level) without implying user input.</p>

## Try it

<Demo of={Default} meta={MeterMeta} />

## Usage

Set `value`, `min`, and `max` to define the range. Add `label` text so the measurement is self-explanatory, it is also the accessible name.

```tsx
import { RuiMeter } from '@ecopages/radiant-ui/meter';

<RuiMeter value={72} min={0} max={100} label="Storage used" />
```

The percent readout is derived from `value` / `min` / `max` and shown next to the bar. `value` below `min` or above `max` is clamped to the range, so the bar and readout stop at `0%` / `100%` like the native element.

## Meter vs progress bar

<p>Use Meter for static measurements. Use a progress element when showing completion of an in-flight task.</p>

## Theming

Meters use **primary** for the filled bar, **track** tokens for the unfilled track (`--rui-track-fill`, overridable with `--rui-track-color` on an ancestor), and **`--radius-control`** for corner rounding so the bar follows the selected theme. The value readout uses `--on-surface`. No status role is applied; the meter is a neutral scalar display, not a status indicator.

Override bar chrome on the host:

```css
rui-meter {
	--rui-meter-fill-color: var(--primary);
	--rui-meter-radius: var(--radius-control);
}
```

```tsx
<RuiMeter value={72} min={0} max={100} label="Storage used" />
```

## Accessibility

- The bar is the native `<meter>` element, exposing `role="meter"` with `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`.
- Include a text label describing what is being measured; the numeric readout is decorative (`aria-hidden="true"`).
- Supplement the bar with a numeric value when precision matters.

## API

`RuiMeter` is the `<rui-meter>` custom-element class and `RuiMeterElement` is an alias for the same class. Its `render()` owns the label, native `<meter>`, and percent readout. Pass props only; there is no authored child contract, and children on `RuiMeter` or `<rui-meter>` are a type error.

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | `0` | Current value. |
| `min` | `number` | `0` | Range minimum. |
| `max` | `number` | `100` | Range maximum. |
| `label` | `string` | `''` | Text describing what is measured (accessible name). |

### CSS classes

Public BEM classes on the composed light-DOM surface (documented via `@cssclass` on the element):

| Class | Description |
| --- | --- |
| `.rui-meter` | Root row (label, bar, value). |
| `.rui-meter__label` | Text describing the measurement. |
| `.rui-meter__bar` | The visually hidden native `<meter>`. |
| `.rui-meter__track` | Presentational track. |
| `.rui-meter__fill` | Presentational filled portion. |
| `.rui-meter__value` | Numeric readout (`aria-hidden`). |

### CSS custom properties

| Property | Default | Description |
| --- | --- | --- |
| `--rui-meter-track-color` | `--rui-track-color` / `--rui-track-fill` | Unfilled track. |
| `--rui-meter-fill-color` | `--primary` | Filled portion. |
| `--rui-meter-radius` | `--radius-control` | Track and fill corner radius. |
| `--rui-meter-height` | `0.75rem` | Bar block size. |
| `--rui-meter-width` | `12rem` | Bar inline size. |

### Theme roles

| Role | CSS variables consumed |
| --- | --- |
| primary | `--primary` (bar fill) |
| track | `--rui-track-fill` (bar track) |
| control radius | `--radius-control` (bar shape) |
| surface text | `--on-surface` (value readout) |