# Speed Gauge

> A picture of speed: a dial with a lit arc, ticks around its edge, and a needle near the top of its range.

- Name: `speed-gauge`
- Status: beta
- Categories: speed, performance, gauge, fast
- Files: the install writes `speed-gauge.tsx`, and any part files named `speed-gauge-*.tsx`, to your `components` alias, `@/components` by default. Edit them freely. They are yours.
- Gallery: https://arbokui.com/illustrations/speed-gauge
- Registry item: https://arbokui.com/r/speed-gauge.json

## Install

1. Add the registry to `components.json`. Do this first, once:

   ```bash
   npx shadcn@latest registry add "@arbokui=https://arbokui.com/r/{name}.json"
   ```

   The command writes this entry. You can also add it by hand:

   ```json
   {
     "registries": {
       "@arbokui": "https://arbokui.com/r/{name}.json"
     }
   }
   ```

   Without this step, the shadcn CLI looks up `@arbokui` in a public list that Arbokui does not control.

2. Add the theme once per app. It replaces your color tokens with ones checked for contrast:

   ```bash
   npx shadcn@latest add @arbokui/theme
   ```

3. Add the illustration. It also adds every component it uses:

   ```bash
   npx shadcn@latest add @arbokui/speed-gauge
   ```

## Use it for

- A feature section about speed, like small parts that keep pages fast.
- Put it in a Feature Grid item's \`illustration\`, or a Bento Card's \`preview\`.
- Set \`value\` from 0 to 1 to move the needle. The default sits near the top.
- Write \`label\` as one sentence that says what the picture shows. Screen readers hear it in place of the drawing.

## Avoid it for

- A real reading people check, like a score or a load. Use Ring Progress or a chart.
- A small icon beside text. Use an icon from lucide-react.

## Props

- `value`: `number`. Default `0.78`. How far the needle points, from 0 to 1. Values outside are held to that range.
- `label`: `string`. Default `a sentence about the dial`. What the picture says, read out in its place.
- `tone`: `"neutral" | "brand" | "danger" | "success" | "warning"`. Default `"neutral"`. The color of the lit arc and the needle's glow.
- `pattern`: `boolean`. Default `true`. A field of dots behind the gauge.
- `className`: `string`. Extra classes on the root.

## Accessibility

- The root is one image, named by \`label\`. The drawing is hidden from screen readers.
- Nothing inside takes focus.
- On hover the glow at the needle's tip fades up. It is a fade, so it stays with reduced motion, and it stops when motion is off.

## Examples

### The default gauge

```tsx
<SpeedGauge />
```

### In green

```tsx
<SpeedGauge tone="success" label="Every part stays small, so pages load fast." />
```