Meter
Semantic gauge display with color-coded fill zones (success, warning, error) based on configurable low/high/optimum thresholds.
<arc-meter>Overview
Meter is a visual gauge that represents a scalar value within a known range, similar to the native HTML <meter> element but with ARC UI styling and full theme integration. The component renders a rounded track with an animated fill bar whose color changes based on the value's relationship to configurable thresholds. When a label is provided, a header row displays the label on the left and the current percentage on the right in monospace font.
The color logic mirrors the HTML meter algorithm using three thresholds: low, high, and optimum. When the optimum is in the high segment (e.g. battery level), values above high render in green (success), values between low and high in yellow (warning), and values below low in red (error). When the optimum is in the low segment (e.g. error count), the logic inverts. Low values are green and high values are red. If thresholds are not set, the component divides the range into thirds.
Meter uses role="meter" with aria-valuenow, aria-valuemin, and aria-valuemax for full accessibility. The fill width and color transitions are animated using the theme's base transition timing, creating smooth visual updates when the value changes programmatically.
Guidelines
When to use
- Set `low`, `high`, and `optimum` to match the semantic meaning of your data (e.g. optimum near max for battery level)
- Provide a `label` so users understand what the meter represents and can read the percentage
- Use Meter for known-range scalar values like disk usage, battery level, signal strength, or performance scores
- Update the `value` prop reactively to reflect real-time data changes with smooth animations
- Pair Meter with adjacent text or tooltips to explain what the color zones mean in your context
When not to use
- Do not use Meter for indeterminate progress. Use Progress with an indeterminate state instead
- Do not use Meter for task completion tracking. Use Progress for sequential step-based workflows
- Do not set `min` equal to or greater than `max`. The fill calculation returns 0% in that case
- Do not rely on color alone to convey the zone meaning. Always include a label or supplementary text
- Avoid using Meter for binary states (pass/fail). Use a Badge or status indicator instead
Features
- `mode="plain"` for a quantity that is not good or bad, and `mode="diverging"` for a lean either way around `center` (−1 to +1), each side its own colour
- Color-coded fill bar: green (success) when the value is in the optimal zone, yellow (warning) for intermediate, red (error) for critical
- Configurable `low`, `high`, and `optimum` thresholds mirroring the HTML `<meter>` algorithm
- Header row showing label text and current percentage in monospace font when `label` is set
- Animated fill width and color transitions using the theme base timing function
- Automatic zone calculation with third-based defaults when thresholds are omitted
- Semantic `role="meter"` with `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`
- Rounded 8px track with `bg-elevated` background matching the design system surface palette
- Value clamped between `min` and `max`, so out-of-range values are safe
Preview
Battery Level
82%
Error Rate
45%
Lean
+0.4
Usage
<arc-meter
label="Disk Usage"
value="72"
min="0"
max="100"
low="50"
high="80"
optimum="0"
></arc-meter>import { Meter } from '@arclux/arc-ui-react';
export default function Example() {
return (
<Meter
label="Disk Usage"
value={72}
min={0}
max={100}
low={50}
high={80}
optimum={0}
/>
);
}<script setup>
import { Meter } from '@arclux/arc-ui-vue';
</script>
<template>
<Meter
label="Disk Usage"
:value="72"
:min="0"
:max="100"
:low="50"
:high="80"
:optimum="0"
/>
</template><script>
import { Meter } from '@arclux/arc-ui-svelte';
</script>
<Meter
label="Disk Usage"
value={72}
min={0}
max={100}
low={50}
high={80}
optimum={0}
/>import { Component } from '@angular/core';
import { Meter } from '@arclux/arc-ui-angular';
@Component({
imports: [Meter],
template: `
<arc-meter
label="Disk Usage"
[value]="72"
[min]="0"
[max]="100"
[low]="50"
[high]="80"
[optimum]="0"
></arc-meter>
`,
})
export class MyComponent {}import { Meter } from '@arclux/arc-ui-solid';
export default function Example() {
return (
<Meter
label="Disk Usage"
value={72}
min={0}
max={100}
low={50}
high={80}
optimum={0}
/>
);
}import { Meter } from '@arclux/arc-ui-preact';
export default function Example() {
return (
<Meter
label="Disk Usage"
value={72}
min={0}
max={100}
low={50}
high={80}
optimum={0}
/>
);
}<!-- Auto-generated by @arclux/prism — do not edit manually -->
<!-- arc-meter — requires meter.css + tokens.css (or arc-ui.css) -->
<div class="arc-meter">
<div
class="meter"
role="meter"
aria-valuemin="Min"
aria-valuemax="Max"
aria-valuenow="Value"
aria-label="Label"
>
Label
<div class="meter__track">
<div
class="meter__fill meter__fill--"
style="width: %"
></div>
</div>
</div>
</div><!-- Auto-generated by @arclux/prism — do not edit manually -->
<!-- arc-meter — self-contained, no external CSS needed -->
<style>
@media (prefers-reduced-motion: reduce) {
.arc-meter *,
.arc-meter *::before,
.arc-meter *::after { animation-duration: 0.01ms !important;
animation-iteration-count: 1 !important;
transition-duration: 0.01ms !important; }
}
</style>
<div class="arc-meter" style="display: block">
<div
style="display: flex; flex-direction: column; gap: 4px"
role="meter"
aria-valuemin="Min"
aria-valuemax="Max"
aria-valuenow="Value"
aria-label="Label"
>
Label
<div style="position: relative; width: 100%; height: 8px; background: rgb(26, 26, 80); border-radius: 9999px; overflow: hidden">
<div
style="width: %"
></div>
</div>
</div>
</div>API
labelstring''- Label text displayed in the header row alongside the current percentage.
valuenumber0- Current meter value. Clamped between
minandmax. Reflected as an attribute. minnumber0- Minimum value representing the left edge (empty) of the meter.
maxnumber100- Maximum value representing the right edge (full) of the meter.
lownumber0- Threshold below which the value is considered low. Used for color zone calculation.
highnumber0- Threshold above which the value is considered high. Used for color zone calculation.
optimumnumber0- The optimal value. Determines which end of the range is "good" for color zone logic.
mode'zones' | 'plain' | 'diverging''zones'- How the fill is coloured.
zones(the default) colours by the low/high/optimum thresholds in status colours.plainis one colour,--meter-fill(default the accent), for a quantity that is not good or bad.divergingfills fromcentertoward the value,--meter-belowon one side and--meter-aboveon the other (default chart series 1 and 2), for a lean either way, such as −1 to +1. centernumber0- The midpoint of a diverging meter. Defaults to halfway between
minandmax. Ignored by the other modes.