# ASCII Gauge

> A dial for one value, drawn in braille.

Category: Charts. Docs: https://asciicn.sumak.dev/docs/ascii-gauge

## Installation

```bash
npx shadcn@latest add @asciicn/ascii-gauge
```

Needs the `@asciicn` registry in components.json: `"registries": { "@asciicn": "https://asciicn.sumak.dev/r/{name}.json" }`.

## Usage

```tsx
import { AsciiGauge } from "@/components/ascii/ascii-gauge"

<AsciiGauge value={64} label="cpu" format={(v) => `${v}%`} />
```

## Examples

### Half circles with ticks

`sweep={180}` gives a flatter gauge that sits well in a row. Colour the arc by threshold with `indicatorClassName`.

```tsx
<AsciiGauge
  value={93}
  label="storage"
  sweep={180}
  ticks={4}
  width={20}
  indicatorClassName={value >= 85 ? "text-destructive" : "text-primary"}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` |  | Clamped to `min` and `max`. |
| `label` | `string` |  | Names the meter and is shown under the value. |
| `min / max` | `number` | `0 / 100` | Range of the dial. |
| `width` | `number` | `24` | Width in characters. The height follows from the sweep. |
| `sweep` | `number` | `270` | Arc length in degrees: 270 for a dial, 180 for a half circle. |
| `ticks` | `number` | `0` | Divisions marked around the outside. |
| `thickness` | `number` | `auto` | Arc thickness in braille dots. |
| `format` | `(v) => string` | `rounded` | Formats the value and the range labels. |
| `indicatorClassName` | `string` | `"text-primary"` | Colour of the filled arc. Swap it at a threshold for warnings. |
| `showRange` | `boolean` | `true` | Show `min` and `max` under the ends of the arc. |

## Notes

- **Accessibility.** `role="meter"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and the formatted value as `aria-valuetext`. The braille is hidden from screen readers.
- **Precision.** The arc is drawn on the braille dot grid, 2×4 dots per character. Dots come out round at line-height 1.2 in a 0.6em-wide monospace font.
- **Geometry.** `gauge()` is exported and returns the text layers plus the centre and radii in dots, for custom labels.
- **Dependencies.** None. Plain text, safe in Server Components.