# Gauge
A circular visual for conveying a percentage.
---
## Default
```tsx
import { Gauge } from '@vercel/geistcn/components';
import type { JSX } from 'react';
export function Component(): JSX.Element {
return (
);
}
```
## Label
```tsx
import { Gauge } from '@vercel/geistcn/components';
import type { JSX } from 'react';
export function Component(): JSX.Element {
return (
);
}
```
## Default color scale
```tsx
import { Gauge } from '@vercel/geistcn/components';
import type { JSX } from 'react';
export function Component(): JSX.Element {
return (
);
}
```
## Custom color range
```tsx
import { Gauge } from '@vercel/geistcn/components';
import type { JSX } from 'react';
export function Component(): JSX.Element {
return (
);
}
```
## Custom secondary color
```tsx
import { Gauge } from '@vercel/geistcn/components';
import type { JSX } from 'react';
export function Component(): JSX.Element {
return (
);
}
```
## Arc priority
When using the gauge to display a ratio, use the `equal` arc priority to make both arcs are equally sized.
```tsx
import { Gauge } from '@vercel/geistcn/components';
import type { JSX } from 'react';
export function Component(): JSX.Element {
return (
);
}
```
## Indeterminate
```tsx
import { Gauge } from '@vercel/geistcn/components';
import type { JSX } from 'react';
export function Component(): JSX.Element {
return (
);
}
```
## Best Practices
### When to use
* A 0–100 ratio against a fixed maximum where the comparison is the point, like quota usage, build cache hit rate, uptime, or billing-period consumption.
* For determinate task progress with a known total (uploads, multi-step setup), use `Progress`.
* For binary or enumerated state, use `Status Dot` for deployments or `Badge` for everything else.
### Behavior
* Use `arc="equal"` for true ratios so 50% reads as exactly half. Use the default `primary` arc for single-percentage usage where the filled portion is the story.
* Threshold colors should match the same numeric breakpoints used elsewhere in the product (`>=80%` warning, `>=95%` error). Don’t invent gauge-only thresholds.
* Pair `indeterminate` with explanatory copy nearby (`Calculating usage…`) so the user knows the value is loading, not zero.
### Content
* Always pair the gauge with an adjacent label or `Tooltip` naming what the number represents (`Build Cache Hit Rate`). The gauge alone is not self-describing.
* Don’t put units inside `children`; the label carries the unit (`Uptime · 99.97%`). `children` is reserved for an icon overlay.
* When `showValue` is on, the rendered number is the value only. Never inject a `%` or unit string into the prop.
### Accessibility
* The component sets `role="progressbar"` with `aria-valuemin`, `aria-valuemax`, and `aria-valuenow`. Don’t override those.
* The adjacent label is the gauge’s accessible name. Tie it with `aria-labelledby` on the gauge wrapper so screen readers read “Uptime, 99 percent.”
* Don’t use color to encode the threshold without redundant text; pair the warning tint with copy below or in the Tooltip.