Gauge

Radial gauge displaying a scalar value on an arc with color-coded zones (success, warning, error) and an animated sweep.

Components

Gauge

data

static

<arc-gauge>

Overview

Gauge is the radial companion to Meter: the same scalar value, range, and threshold semantics, drawn as an arc instead of a bar. A neutral track arc carries a value arc whose stroke takes the zone color and a soft matching glow, and the current reading sits center-stage in monospace type with an optional `unit` suffix and a label beneath it. Two shapes are available through `variant`: the default `full` renders a 270-degree horseshoe with the readout inside the ring, while `half` renders a 180-degree semicircle with the readout resting on the baseline. The color logic mirrors the HTML meter algorithm using the same three thresholds as Meter: `low`, `high`, and `optimum`. When the optimum is in the high segment (e.g. battery level), values above `high` render green (success), values between `low` and `high` yellow (warning), and values below `low` red (error). When the optimum is in the low segment (e.g. error rate), the logic inverts. Low values are green and high values are red. If thresholds are omitted, the range divides into thirds. The value arc sweeps into place on first paint and animates smoothly whenever the value changes, honoring the reduced-motion preference. Gauge uses `role="meter"` with `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`; when a `unit` is set, `aria-valuetext` reports the reading with its unit so screen readers announce "72%" rather than a bare number.

Guidelines

When to use

Use Gauge for a single reading that deserves visual prominence on a dashboard: CPU load, battery, a health score
Set `low`, `high`, and `optimum` to match the semantic meaning of your data, exactly as you would on Meter
Provide a `label` so the reading has an accessible name and visible context
Set `unit` when the raw number is ambiguous: "72" reads differently as %, ms, or GB
Use the `half` variant when vertical space is tight, such as inside a stat row or card header

When not to use

Do not use Gauge where space is dense or readings stack in a list. Meter conveys the same data in a fraction of the height
Do not use Gauge for a plain number with no meaningful range. Stat presents a standalone figure with trend context instead
Do not use Gauge for task progress. Progress communicates completion; Gauge communicates where a reading sits in a range
Do not set `min` equal to or greater than `max`. The sweep renders empty in that case
Do not rely on color alone to convey the zone meaning. Keep the value and label visible or provide adjacent text

Features

`mode="plain"` for a quantity that is not good or bad, and `mode="diverging"` for a lean either way around `center`, each side its own colour
Color-coded value arc: green (success) in the optimal zone, yellow (warning) for intermediate, red (error) for critical
Configurable `low`, `high`, and `optimum` thresholds identical to Meter, mirroring the HTML `<meter>` algorithm
Soft glow on the value arc in the zone color, following the status glow scale
Animated sweep on first paint and on every value change, disabled under reduced motion
`full` (270-degree horseshoe) and `half` (180-degree) arc variants
Center-stage monospace readout with optional `unit` suffix and label, hidden via `showValue`
Semantic `role="meter"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and unit-aware `aria-valuetext`
Value clamped between `min` and `max`, so out-of-range values are safe

Preview

Usage

<arc-gauge
  label="CPU Load"
  value="72"
  unit="%"
  min="0"
  max="100"
  low="50"
  high="80"
  optimum="0"
></arc-gauge>

import { Gauge } from '@arclux/arc-ui-react';

export default function Example() {
  return (
    <Gauge
      label="CPU Load"
      value={72}
      unit="%"
      min={0}
      max={100}
      low={50}
      high={80}
      optimum={0}
    />
  );
}

<script setup>
import { Gauge } from '@arclux/arc-ui-vue';
</script>

<template>
  <Gauge
    label="CPU Load"
    :value="72"
    unit="%"
    :min="0"
    :max="100"
    :low="50"
    :high="80"
    :optimum="0"
  />
</template>

<script>
  import { Gauge } from '@arclux/arc-ui-svelte';
</script>

<Gauge
  label="CPU Load"
  value={72}
  unit="%"
  min={0}
  max={100}
  low={50}
  high={80}
  optimum={0}
/>

import { Component } from '@angular/core';
import { Gauge } from '@arclux/arc-ui-angular';

@Component({
  imports: [Gauge],
  template: `
    <arc-gauge
      label="CPU Load"
      [value]="72"
      unit="%"
      [min]="0"
      [max]="100"
      [low]="50"
      [high]="80"
      [optimum]="0"
    ></arc-gauge>
  `,
})
export class MyComponent {}

import { Gauge } from '@arclux/arc-ui-solid';

export default function Example() {
  return (
    <Gauge
      label="CPU Load"
      value={72}
      unit="%"
      min={0}
      max={100}
      low={50}
      high={80}
      optimum={0}
    />
  );
}

import { Gauge } from '@arclux/arc-ui-preact';

export default function Example() {
  return (
    <Gauge
      label="CPU Load"
      value={72}
      unit="%"
      min={0}
      max={100}
      low={50}
      high={80}
      optimum={0}
    />
  );
}

API

labelstring='': Label text displayed beneath the value and used as the accessible name.
unitstring='': Unit suffix rendered after the value (e.g. "%", "ms", "GB").
valuenumber=0: Current gauge value. Clamped between min and max. Reflected as an attribute.
minnumber=0: Minimum value representing the empty end of the arc.
maxnumber=100: Maximum value representing the full end of the arc.
lownumber=0: Threshold below which the value is considered low. Used for color zone calculation.
highnumber=0: Threshold above which the value is considered high. Used for color zone calculation.
optimumnumber=0: The optimal value. Determines which end of the range is "good" for color zone logic.
variant'full' | 'half'='full': Arc shape: full is a 270-degree horseshoe, half a 180-degree semicircle.
mode'zones' | 'plain' | 'diverging'='zones': How the arc is coloured. zones (the default) colours by the low/high/optimum thresholds in status colours. plain is one colour, --gauge-fill (default the accent), for a quantity that is not good or bad. diverging draws from center toward the value, --gauge-below on one side and --gauge-above on the other (default chart series 1 and 2), for a lean either way, such as −1 to +1. A custom colour's glow reads the matching -rgb property (--gauge-fill-rgb and so on).
centernumber=0: The midpoint of a diverging gauge. Defaults to halfway between min and max. Ignored by the other modes.
showValueboolean=true: Whether to render the numeric value in the center of the arc. Defaults to true; disable via the showValue property.

Gauge

Overview

Guidelines

When to use

When not to use

Features

Preview

Usage

API

See Also

Docs

Project

Arclight