# 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.

Use `Progress` for a task that advances. Show the value or describe it in nearby text, since color alone is not enough.

## 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` or `positive`. It defaults to `neutral`.

```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: '4' })
}
```

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

### Size

Set `size` to `small`, `medium`, or `large`. It defaults to `medium`.

```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: '4' })
}
```

[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: '4' })
}
```

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

## Guidelines

TODO: Write guidelines for Gauge.