# Gauge
> Semicircular gauge of green, amber and red cells with a sprung pointer; the zone word rolls when the value crosses a threshold.
- Element: `<hf-gauge>`
- React: `import { HfGauge } from "@/components/lumesec/hf-gauge"`
- Collection: Pixel HD (https://elements.lumesec.ai/components/pixel-hd)
- Registry item: https://elements.lumesec.ai/r/hf-gauge.json
- Page: https://elements.lumesec.ai/components/pixel-hd/gauge



Live preview: https://elements.lumesec.ai/view/hf-gauge

```html
<hf-gauge value="72" label="Rate limit" zones="60,85"></hf-gauge>
```

## Playground

Change a prop and the component updates. Props marked live animate to the new value; the others rebuild the element.

## Installation

```bash
npx shadcn@latest add @lumesec/hf-gauge
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/hf-gauge.json
```

## Usage

React:

```tsx
import { HfGauge } from "@/components/lumesec/hf-gauge";

export function Example() {
  return (
    <HfGauge value={72} label="Rate limit" zones="60,85" />
  );
}
```

HTML:

```html
<script type="module" src="https://elements.lumesec.ai/cdn/hf-gauge.js"></script>

<hf-gauge value="72" label="Rate limit" zones="60,85"></hf-gauge>
```

## Behaviour

A semicircle of green, amber and red cells with a sprung pointer and a shimmer in the filled part. Past the last zone it pulses. The status word rolls when the zone changes.

## API reference

### Attributes

| Attribute  | React prop | Type     | Default      | Description                                                                                            |
| ---------- | ---------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------ |
| `value`    | `value`    | `number` | `42`         | Current value, clamped to `min`–`max`. Observed.                                                       |
| `min`      | `min`      | `number` | `0`          | Lower bound. Not observed; read when `value` changes.                                                  |
| `max`      | `max`      | `number` | `100`        | Upper bound. Not observed; read when `value` changes.                                                  |
| `zones`    | `zones`    | `string` | `60,85`      | Two thresholds in value units, comma-separated: `Elevated` from the first, `Critical` from the second. |
| `decimals` | `decimals` | `number` | `0`          | Decimal places in the displayed number.                                                                |
| `label`    | `label`    | `string` | `Rate limit` | Text under the gauge and the start of the `aria-label`.                                                |
| `unit`     | `unit`     | `string` | `%`          | Text after the number. An empty value hides it.                                                        |

### Properties

| Property            | Type               | Description                                           |
| ------------------- | ------------------ | ----------------------------------------------------- |
| `value`             | `number`           | Clamped value. Setting it writes the attribute.       |
| `min` (read-only)   | `number`           | Parsed `min`.                                         |
| `max` (read-only)   | `number`           | Parsed `max`.                                         |
| `frac` (read-only)  | `number`           | Position of the value in the range, 0 to 1.           |
| `zones` (read-only) | `[number, number]` | The two thresholds as fractions of the range, 0 to 1. |

## Accessibility

* The canvas has `role="meter"` with `aria-valuemin`, `aria-valuemax`, `aria-valuenow` and an `aria-label` such as `Rate limit: 72%, Elevated`.
* The number and zone word are plain text; there is no live region.
* Reduced motion: the pointer jumps without the spring, the shimmer and the critical pulse are off, and the number and zone word swap without rolling.

## Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--foreground`, `--lumesec`, `--lumesec-success` and `--muted-foreground`.

To restyle only LumeSec elements, set the matching `--ui-*` overrides: `--ui-accent`, `--ui-fg`, `--ui-muted` and `--ui-ok`.

## Notes

* The visible `label` and `unit` text is set once on connect; the `aria-label` re-reads both on each `value` change.