GaugeChart
A circular gauge chart for displaying a value within a range. Perfect for showing performance metrics, progress, or status indicators. Features configurable arcs, tic marks, and color zones.
Features
- Circular gauge display with configurable arc angles
- Customizable min/max range
- Needle indicator
- Percentage display
- Customizable colors
- Optional label and unit
- Responsive sizing
- Configurable tic marks with labels
- Color zones for value ranges
- Min/max labels at arc endpoints
Examples
Basic GaugeChart
Performance Score
<script>
import { GaugeChart } from '$lib';
</script>
<GaugeChart
value={75}
min={0}
max={100}
label="Performance Score"
unit="%"
color="primary"
/>With Tic Marks
Customer Satisfaction
With Color Zones
Walmart's Customer Satisfaction Score
Full Circle Gauge
System Health
Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | number | Required | Current value |
min | number | 0 | Minimum value |
max | number | 100 | Maximum value |
label | string | undefined | Gauge label |
unit | string | undefined | Unit of measurement |
color | string | 'primary' | Gauge color theme (primary, secondary, success, danger, warning, info) |
size | number | 200 | Gauge size in pixels |
arcStart | number | 0 | Arc start angle in degrees (0 = horizontal left, 90 = vertical top) |
arcEnd | number | 180 | Arc end angle in degrees |
tics | TicConfig | {} | Tic mark configuration (show, step, values, showLabels, format) |
zones | ColorZone[] | [] | Color zones for value ranges (start, end, color, label) |
Tic Configuration
The tics prop accepts an object with the following properties:
| Property | Type | Description |
|---|---|---|
show | boolean | Show tic marks |
step | number | Step size for tics (if not using custom values) |
values | number[] | Custom values to show as tics (overrides step) |
showLabels | boolean | Show tic labels |
format | (value: number) => string | Format function for tic labels |
Color Zones
The zones prop accepts an array of objects with the following properties:
| Property | Type | Description |
|---|---|---|
start | number | Start value for the zone |
end | number | End value for the zone |
color | string | Color for the zone (hex or CSS color) |
label | string | Optional label for the zone |
Best Practices
- Use for single metric displays
- Include meaningful labels and units
- Use color zones to indicate status ranges
- Keep ranges intuitive and meaningful
- Use tic marks to help users understand the scale
- Angle specifications: 0° = horizontal left, 90° = vertical top, 180° = horizontal right, 270° = vertical bottom