# Meter
## Summary
`Meter` shows a bounded quantitative value, typically without the temporal progress semantics of a progress bar. It is the descriptive-measurement bar when the UI should read as level, score, capacity, or quality rather than task completion.
## Imports
```tsx
import {
Meter,
MeterTrack,
type MeterProps,
type MeterSize,
type MeterVariant,
} from '@vega-ui/react';
```
## Exported Types
- `MeterProps`
- `MeterTrackProps`
- `MeterSize`
- `MeterVariant`
## Minimal Composition
`max` defaults to `1`, so a fraction like `0.72` needs no `max`; pass `max` for any other scale (`value={36} max={50}`). The meter has no visible label of its own: give it `aria-label` or `aria-labelledby`.
```tsx
import { Meter, MeterTrack } from '@vega-ui/react';
export default function MinimalComposition() {
return (
);
}
```
## Required Parts
- `Meter`: root meter surface
- `MeterTrack`: visible measured-fill track
## Optional Parts
- No extra public parts beyond root and track
## Composition Order
1. `Meter`
2. `MeterTrack`
## Variants
- Sizes: `sm`, `md`, `lg`
- Variants: `primary`, `secondary`
- States: neutral, good, warn, bad via thresholds
## Edge Cases
- `Meter` is for bounded measurement, not async completion.
- Threshold props like `low`, `high`, and `optimum` can shift the semantic color state.
- Surrounding copy should explain the measured value and range.
- If the measurement is actually composed of several meaningful parts, `MeterStack` is usually clearer than one continuous bar.
## Common Mistakes
- Using `Meter` for loading or async work.
- Showing a value without explaining the range or meaning.
- Ignoring threshold semantics when they matter to interpretation.
## Examples
### Basic
#### Basic: storage usage with a visible summary
A meter on a real scale: `max` is the plan limit, so `value` is passed in gigabytes, not as a fraction. The visible heading names the meter through `aria-labelledby`, and `valueText` repeats the human-readable summary for screen readers instead of a bare number.
```tsx
import { Meter, MeterTrack, Text } from '@vega-ui/react';
import { useId } from 'react';
export default function StorageUsage() {
const labelId = useId();
const usedGb = 36.2;
const limitGb = 50;
const summary = `${usedGb} GB of ${limitGb} GB used`;
return (
Cloud storage{summary}
);
}
```
### Controlled/Stateful
#### Controlled/Stateful: battery level with threshold zones
The parent owns the level and passes it to the meter together with `low`, `high` and `optimum`. The track turns red, amber or green on its own, while the same thresholds drive a text status linked through `aria-describedby`, so the meaning never relies on color.
```tsx
import { Button, Meter, MeterTrack, Text } from '@vega-ui/react';
import { useId, useState } from 'react';
export default function BatteryLevel() {
const labelId = useId();
const statusId = useId();
const [level, setLevel] = useState(64);
let status = 'Battery is fine';
if (level < 20) {
status = 'Battery is low — connect the charger';
} else if (level > 80) {
status = 'Battery is almost full';
}
const discharge = () => setLevel(Math.max(level - 15, 0));
const charge = () => setLevel(Math.min(level + 15, 100));
return (
Headphones battery{level}%
{status}
);
}
```
### Form/Integration
#### Form/Integration: character limit under a textarea
The meter follows the length of a `TextArea` inside a real form. `optimum={0}` makes short text the good zone, so the bar turns amber near the limit and red at it; `maxLength` enforces the hard cap and the remaining count is linked to the field. The submit handler reads the value with `FormData`, and reset clears the state.
```tsx
import { Button, HelperText, Label, Meter, MeterTrack, TextArea } from '@vega-ui/react';
import { FormEvent, useId, useState } from 'react';
export default function BioLengthMeter() {
const fieldId = useId();
const counterId = useId();
const limit = 160;
const [bio, setBio] = useState('Product designer in Lisbon. I write about design systems and accessible forms.');
const [saved, setSaved] = useState(null);
const left = limit - bio.length;
const handleSubmit = (event: FormEvent) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
const value = String(data.get('bio'));
setSaved(`Saved, ${value.length} characters`);
};
const handleReset = () => {
setBio('');
setSaved(null);
};
return (