# Throughput gauge
> Half-circle pixel gauge for tokens per second with amber and red zones, a spring needle that overshoots and a peak marker.
- Element: `<px-gauge>`
- React: `import { PxGauge } from "@/components/lumesec/px-gauge"`
- Collection: Pixel Lab (https://elements.lumesec.ai/components/pixel-lab)
- Registry item: https://elements.lumesec.ai/r/px-gauge.json
- Page: https://elements.lumesec.ai/components/pixel-lab/gauge



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

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

<px-gauge></px-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/px-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/px-gauge.json
```

## Usage

React:

```tsx
import { PxGauge } from "@/components/lumesec/px-gauge";

export function Example() {
  return (
    <PxGauge />
  );
}
```

HTML:

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

<px-gauge></px-gauge>
```

## Behaviour

Tokens per second on four rings of pixels, with amber and red zones. The needle is a spring, so it overshoots and settles, and a peak marker hangs at the high point before sliding back.

## API reference

### Attributes

| Attribute | React prop | Type     | Default | Description                                                                                           |
| --------- | ---------- | -------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `max`     | `max`      | `number` | `200`   | Full-scale value of the gauge and its tick labels. Read every frame, so a change applies immediately. |

### Properties

| Property          | Type     | Description                                            |
| ----------------- | -------- | ------------------------------------------------------ |
| `max` (read-only) | `number` | Parsed `max` attribute, `200` when missing or invalid. |

## Keyboard

| Keys                                | Action                                              |
| ----------------------------------- | --------------------------------------------------- |
| Space / Enter (on the boost button) | Boost while held; releasing the key ends the boost. |

## Accessibility

* The dial (canvas and reading) has `role="meter"`, `aria-label="Output speed in tokens per second"` and `aria-valuemin="0"`.
* `aria-valuenow`, `aria-valuemax` and `aria-valuetext` ("72 tokens per second") are updated about twice per second; the visible reading is text inside the meter.
* The "Hold to boost" button is a native button with `aria-pressed` reflecting the boost state.
* Reduced motion: the needle tracks the value directly without spring overshoot and the red zone stops flickering.

## 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 `--destructive`, `--foreground`, `--lumesec` and `--muted-foreground`.

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

## Notes

* The reading is simulated demo data: it idles around 36% of `max` with noise and climbs to about 93% while boosted. There is no attribute for feeding a real value.
* Pressing and holding the button or the gauge itself boosts it; the amber zone starts at 70% of `max` and the red zone at 86%.
* The reading is set in the monospace font, scales with the dial and turns red in the red zone.
* The canvas is 180px tall.