# Gauge

Shows a measurement within a range as a ring.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Gauge.tsx)

## Overview

A gauge is a ring that shows a measurement within a range, such as usage or a score.

## Examples

### Basic

```tsx
import { Gauge } from '@tempoxyz/ds'

export function Demo() {
  return <Gauge aria-label="Storage used" showValue value={72} />
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Gauge/Basic.tsx)

### Intent

Set `intent` to `neutral` (default) or `positive`.

```tsx
import { Gauge, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['neutral', 'positive'] as const).map((intent, index) => (
        <Gauge aria-label={intent} intent={intent} key={intent} showValue value={20 + index * 20} />
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '16' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Gauge/Intent.tsx)

### Size

Set `size` to `small`, `medium` (default), or `large`.

```tsx
import { Gauge, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      <Gauge aria-label="Small" size="small" value={72} />
      <Gauge aria-label="Medium" size="medium" value={72} />
      <Gauge aria-label="Large" showValue size="large" value={72} />
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '16' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Gauge/Size.tsx)

### ShowValue

Set `showValue` to print the value inside the ring.

```tsx
import { Gauge, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      <Gauge aria-label="Hidden value" value={40} />
      <Gauge aria-label="Shown value" showValue value={40} />
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '16' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Gauge/ShowValue.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Gauge } from '@tempoxyz/ds'

<Gauge />
```

## Guidelines

### When to Use

* Show how much of a limit is used, such as API requests against a quota.
* Show a ratio in a metric tile, such as gas used against the gas limit.
* Show a score with a fixed range, such as validator uptime.

### When Not to Use

* Use [Progress](/docs/components/progress) for a task that advances, such as an upload.
* Use [Skeleton](/docs/components/skeleton) or [Spinner](/docs/components/spinner) while the measurement loads.
* Use [Slider](/docs/components/slider) when the user sets the value.
* Use plain text if the value has no fixed maximum, such as 4,812 TPS.

### Show the Value in Text

Set `showValue` to print the percentage in the ring.

**Do:** Pair the ring with its label and the absolute values beside it.

```tsx
/**
 * Do example for "Show the Value in Text" on the Gauge page.
 * Pair the ring with its label and the absolute values beside it.
 * @module
 */
import { Gauge, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <Gauge aria-labelledby="gauge-requests" max={10000} showValue value={7200} />
      <div {...styles.text()}>
        <div {...styles.label()} id="gauge-requests">
          API requests this month
        </div>
        <div {...styles.value()}>7,200 of 10,000</div>
      </div>
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.primary', typography: 'body.b2' })

  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })

  export const text = style({ display: 'flex', flexDirection: 'column', gap: '4' })

  export const value = style({ color: 'content.secondary', typography: 'body.b3' })
}
```

**Don't:** Show a ring without its value or what it measures.

```tsx
/**
 * Don't example for "Show the Value in Text" on the Gauge page.
 * Don't show a ring without its value or what it measures.
 * @module
 */
import { Gauge } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return <Gauge aria-label="Usage" max={10000} value={7200} />
}
```

### Pass the Real Range

The ring, `showValue`, and the accessible value derive the percentage from `min` (default 0) and `max` (default 100).

**Do:** Set `max` to the actual bound, such as `value={7200}` with `max={10000}`.

```tsx
/**
 * Do example for "Pass the Real Range" on the Gauge page.
 * Set `max` to the actual bound, such as `value={7200}` with `max={10000}`.
 * @module
 */
import { Gauge, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <Gauge aria-labelledby="gauge-range" max={10000} showValue value={7200} />
      <div {...styles.text()}>
        <div {...styles.label()} id="gauge-range">
          API requests this month
        </div>
        <div {...styles.value()}>7,200 of 10,000</div>
      </div>
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.primary', typography: 'body.b2' })

  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })

  export const text = style({ display: 'flex', flexDirection: 'column', gap: '4' })

  export const value = style({ color: 'content.secondary', typography: 'body.b3' })
}
```

**Don't:** Pass a raw count against the default `max` of 100.

```tsx
/**
 * Don't example for "Pass the Real Range" on the Gauge page.
 * Don't pass a raw count against the default `max` of 100.
 * @module
 */
import { Gauge, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <Gauge aria-labelledby="gauge-default" showValue value={7200} />
      <div {...styles.text()}>
        <div {...styles.label()} id="gauge-default">
          API requests this month
        </div>
        <div {...styles.value()}>7,200 of 10,000</div>
      </div>
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.primary', typography: 'body.b2' })

  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })

  export const text = style({ display: 'flex', flexDirection: 'column', gap: '4' })

  export const value = style({ color: 'content.secondary', typography: 'body.b3' })
}
```

### Choose an Intent

* **Most Measurements (neutral):** The default, for a measurement such as API requests against a quota.
* **Full Is Good (positive):** A measurement where a full value is good, such as 100% uptime.
* **Nearing a Limit (Alert):** There is no `warning` intent. Add a `warning` [Alert](/docs/components/alert) with the next step.

### Match Size to Context

* **Small (32px):** Table cells and dense lists. Print the value beside it.
* **Medium (48px):** The default, for metric tiles and cards.
* **Large (80px):** A featured measurement, such as plan usage in billing.

## Content

* **Label:** Name the measurement, not the component, such as Gas used.

## Accessibility

A gauge renders a `meter`. It follows the [WAI-ARIA Authoring Practices meter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/meter/). It is not a live region, so a changed value is read only on the next visit.

### Semantics

* **Root (meter):** Reports its minimum, maximum, and value to assistive technology.
* **Value Text (72%):** Defaults to the value as a locale-formatted percentage of the range.
* **Ring (aria-hidden):** Hidden. Assistive technology reads the value text instead.
* **Visible Value (showValue):** Shows the number. It ignores `format`, which changes only the announced text.
* **Arc Color (foreground):** Green for positive intent, on a gray track. Keep the gauge on a plain surface.
* **Reduced Motion (reduce):** Under reduced motion, the arc doesn't animate between values.

### Your Responsibilities

* **Name the Gauge (SC 4.1.2):** Use `aria-label` or `aria-labelledby`. The gauge renders no label.
* **Describe Non-Percentage Values (getAriaValueText):** Use it if a percentage doesn't describe the value, such as "7.2 of 10 GB".

## Related

[Progress](/docs/components/progress)

Use for a task that advances.

[Alert](/docs/components/alert)

Use for a warning when usage nears a limit.

[Dashboards](/docs/patterns/dashboards)

Covers laying out metric tiles.
