# SvGauge
A radial arc gauge that renders a value within a range, with optional colored
threshold bands, a needle, and a center label.
`SvGauge` is a read-only display control - a classic dashboard dial for a single
KPI. Its arc and needle geometry plus `role="meter"` ARIA live in the headless
`createGauge` core; this component is one styled SVG renderer over it. Pass
`bands` to paint red/amber/green zones along the arc, or leave them off for a
plain accent fill up to the value. Colors come from the grid's `--sg-*` tokens.
Related: [SvSlider](https://svgrid.com/docs/help/ui-components/sv-slider/) · [SvCircularProgress](https://svgrid.com/docs/help/ui-components/sv-circular-progress/) · [Range & meters overview](https://svgrid.com/docs/help/ui-components/range/)
## Installation
Add it with the CLI - this drops a ready-to-edit `SvGauge` starter into your app:
Prefer to see it first? `npx @svgrid/ui try gauge` opens it in a throwaway sandbox - no project needed.
Or install the package and import it directly. `SvGauge` ships free in
`@svgrid/grid` (dependency-free):
The examples on this page import from `@svgrid/grid`:
```svelte
```
```ts
import { SvGauge } from '@svgrid/grid'
```
## Example
> Live demo: Gauge - https://svgrid.com/demos/319-gauge/
```svelte
```
## Props
| Prop | Type | Default | Description |
| ------------- | --------------------------------- | ------- | ----------------------------------------------------------------- |
| `value` | `number` | `0` | The value to display; clamped to `[min, max]`. |
| `min` | `number` | `0` | Lower bound of the arc. |
| `max` | `number` | `100` | Upper bound of the arc. |
| `sweep` | `number` | `270` | Arc sweep in degrees (e.g. `180` for a half gauge). |
| `bands` | `{ from; to; color }[]` | `[]` | Colored threshold zones along the arc. |
| `needle` | `boolean` | `true` | Draw the needle and center hub. |
| `label` | `string` | - | Center label; defaults to the formatted value. |
| `unit` | `string` | `''` | Suffix appended to the value in the default label. |
| `size` | `number` | `180` | Overall diameter in px. |
| `thickness` | `number` | `14` | Arc stroke width in px. |
| `formatValue` | `(v: number) => string` | - | Formats the center value (overridden by `label`). |
| `ariaLabel` | `string` | - | Accessible name for the meter. |
| `dir` | `ltr` \| `rtl` \| `auto` | `auto` | Text direction for the center label / unit. |
## Examples
### Threshold bands
Pass `bands` covering the full range to color the arc by zone. Bands replace the
plain accent fill, so the dial reads good/warning/critical at a glance:
```svelte
```
### Half gauge, no needle
Drop `sweep` to `180` for a semicircle and turn the `needle` off for a compact
progress-style tile with just the value arc:
```svelte
```
### Custom center label
Override the auto label to show something other than the raw number - a rating,
a status word, or a formatted metric:
```svelte
```
### Live KPI dial
Bind `value` to reactive state and the arc tracks the number as it changes; add
`formatValue` to render the reading in its own units and `ariaLabel` to name it:
```svelte
v.toLocaleString()}
bands={[
{ from: 0, to: 5500, color: '#16a34a' },
{ from: 5500, to: 7000, color: '#f59e0b' },
{ from: 7000, to: 8000, color: '#dc2626' },
]}
/>
```
Tip: `value` is clamped to `[min, max]`, so a spike past `max` pins the needle at
full scale rather than sweeping past the end of the arc.
## Accessibility
- The root carries `role="meter"` with value/min/max supplied by the
`createGauge` core, so assistive tech reads it as a live measurement.
- Set `ariaLabel` to name what the gauge measures - the visual label alone is
not announced as the meter's name.
- Purely presentational: it is a display, not a control, and takes no focus.
## More examples
### Gauge - headless
createGauge drives styled SvGauge plus a custom SVG meter sharing the same arc / needle geometry.
> Live demo: Gauge - headless - https://svgrid.com/demos/282-headless-gauge/
### Gauge dial (KPI dashboard)
type: gauge renders a semicircle with track + value arcs, optional red/amber/green range bands, and a target tick. Click any row in the KPI grid to drive the dial; bands auto-flip direction based on whether higher or lower is better.
> Live demo: Gauge dial (KPI dashboard) - https://svgrid.com/demos/163-chart-gauge/
## Sizes
Every control takes the same three sizes, so a dense toolbar and a roomy form can share components.
```svelte
```
## See also
- [Range overview](https://svgrid.com/docs/help/ui-components/range/) - the range-control family at a glance.
- [SvSlider](https://svgrid.com/docs/help/ui-components/sv-slider/) - the interactive sibling for choosing a value.
- [SvCircularProgress](https://svgrid.com/docs/help/ui-components/sv-circular-progress/) - a ring for task completion.
---
SvGrid is the Svelte 5 data grid (`npm install @svgrid/grid`, MIT). This page: https://svgrid.com/docs/help/ui-components/sv-gauge/ . All docs: https://svgrid.com/llms.txt