0
# Gauge Charts
1

2
Gauge components for displaying single values within defined ranges using circular and linear gauge visualizations.
3

4
## Capabilities
5

6
### Circular Gauge
7

8
Standard circular gauge chart for displaying a single value with customizable ranges and visual indicators.
9

10
```typescript { .api }
11
@Component({ selector: 'ngx-charts-gauge' })
12
export class GaugeComponent {
13
  @Input() results: SingleSeries;
14
  @Input() legend: boolean = false;
15
  @Input() legendTitle: string = 'Legend';
16
  @Input() legendPosition: LegendPosition = LegendPosition.Right;
17
  @Input() min: number = 0;
18
  @Input() max: number = 100;
19
  @Input() units: string = '';
20
  @Input() bigSegments: number = 10;
21
  @Input() smallSegments: number = 5;
22
  @Input() showAxis: boolean = true;
23
  @Input() startAngle: number = -120;
24
  @Input() angleSpan: number = 240;
25
  @Input() activeEntries: any[] = [];
26
  @Input() axisTickFormatting: any;
27
  @Input() tooltipDisabled: boolean = false;
28
  @Input() tooltipTemplate: TemplateRef<any>;
29
  @Input() valueFormatting: any;
30
  @Input() showText: boolean = true;
31
  @Input() margin: number[] = [10, 20, 10, 20];
32
  @Input() scheme: any;
33
  @Input() customColors: any;
34
  @Input() animations: boolean = true;
35
  @Input() ariaLabel: string = 'gauge chart';
36
  
37
  @Output() activate: EventEmitter<any> = new EventEmitter();
38
  @Output() deactivate: EventEmitter<any> = new EventEmitter();
39
  @Output() select: EventEmitter<any> = new EventEmitter();
40
}
41
```
42

43
**Usage Examples:**
44

45
```typescript
46
import { Component } from '@angular/core';
47

48
@Component({
49
  selector: 'app-gauge',
50
  template: `
51
    <ngx-charts-gauge
52
      [results]="gaugeData"
53
      [min]="0"
54
      [max]="100"
55
      [units]="'%'"
56
      [bigSegments]="10"
57
      [smallSegments]="5"
58
      [showAxis]="true"
59
      [startAngle]="-120"
60
      [angleSpan]="240"
61
      [valueFormatting]="valueFormatter"
62
      (select)="onSelect($event)">
63
    </ngx-charts-gauge>
64
  `
65
})
66
export class GaugeComponent {
67
  gaugeData = [
68
    { name: 'Progress', value: 73 }
69
  ];
70

71
  valueFormatter = (value: number) => `${value}%`;
72

73
  onSelect(event: any): void {
74
    console.log('Gauge selected:', event);
75
  }
76
}
77
```
78

79
### Linear Gauge
80

81
Horizontal linear gauge for displaying values in a bar-like format.
82

83
```typescript { .api }
84
@Component({ selector: 'ngx-charts-linear-gauge' })
85
export class LinearGaugeComponent {
86
  @Input() results: SingleSeries;
87
  @Input() min: number = 0;
88
  @Input() max: number = 100;
89
  @Input() value: number = 0;
90
  @Input() units: string = '';
91
  @Input() previousValue: number;
92
  @Input() valueFormatting: any;
93
  @Input() scheme: any;
94
  @Input() customColors: any;
95
  @Input() animations: boolean = true;
96
  @Input() tooltipDisabled: boolean = false;
97
  @Input() tooltipTemplate: TemplateRef<any>;
98
  @Input() ariaLabel: string = 'linear gauge';
99
  
100
  @Output() select: EventEmitter<any> = new EventEmitter();
101
}
102
```
103

104
**Linear Gauge Usage:**
105

106
```typescript
107
@Component({
108
  template: `
109
    <ngx-charts-linear-gauge
110
      [value]="currentValue"
111
      [previousValue]="previousValue"
112
      [min]="0"
113
      [max]="1000"
114
      [units]="'units'"
115
      [valueFormatting]="valueFormatter">
116
    </ngx-charts-linear-gauge>
117
  `
118
})
119
export class LinearGaugeComponent {
120
  currentValue = 750;
121
  previousValue = 650;
122
  
123
  valueFormatter = (value: number) => `${value.toLocaleString()} units`;
124
}
125
```
126

127
### Percent Gauge
128

129
Specialized gauge component optimized for percentage values with built-in formatting.
130

131
```typescript { .api }
132
@Component({ selector: 'ngx-charts-percent-gauge' })
133
export class PercentGaugeComponent {
134
  @Input() results: SingleSeries;
135
  @Input() min: number = 0;
136
  @Input() max: number = 100;
137
  @Input() value: number = 0;
138
  @Input() units: string = '%';
139
  @Input() valueFormatting: any;
140
  @Input() scheme: any;
141
  @Input() customColors: any;
142
  @Input() animations: boolean = true;
143
  @Input() tooltipDisabled: boolean = false;
144
  @Input() tooltipTemplate: TemplateRef<any>;
145
  @Input() ariaLabel: string = 'percent gauge';
146
  
147
  @Output() select: EventEmitter<any> = new EventEmitter();
148
  @Output() activate: EventEmitter<any> = new EventEmitter();
149
  @Output() deactivate: EventEmitter<any> = new EventEmitter();
150
}
151
```
152

153
**Percent Gauge Usage:**
154

155
```typescript
156
@Component({
157
  template: `
158
    <ngx-charts-percent-gauge
159
      [results]="percentData"
160
      [min]="0"
161
      [max]="100"
162
      [valueFormatting]="percentFormatter">
163
    </ngx-charts-percent-gauge>
164
  `
165
})
166
export class PercentComponent {
167
  percentData = [
168
    { name: 'Completion', value: 87.5 }
169
  ];
170
  
171
  percentFormatter = (value: number) => `${value.toFixed(1)}%`;
172
}
173
```
174

175
## Gauge Configuration
176

177
### Angle Configuration
178

179
Control the arc span and starting angle of circular gauges.
180

181
```typescript { .api }
182
// Angle configuration
183
@Input() startAngle: number = -120; // Starting angle in degrees (-180 to 180)
184
@Input() angleSpan: number = 240;   // Total angle span in degrees (1 to 360)
185

186
// Common configurations:
187
// Full circle: startAngle = -180, angleSpan = 360
188
// Semi-circle: startAngle = -90, angleSpan = 180  
189
// Three-quarter: startAngle = -120, angleSpan = 240
190
// Quarter circle: startAngle = -45, angleSpan = 90
191
```
192

193
### Tick Configuration
194

195
Customize gauge axis ticks and segments.
196

197
```typescript { .api }
198
// Tick mark configuration
199
@Input() bigSegments: number = 10;   // Number of major tick marks
200
@Input() smallSegments: number = 5;  // Number of minor ticks between major ticks
201
@Input() showAxis: boolean = true;   // Show/hide axis and tick marks
202
@Input() axisTickFormatting: any;    // Custom tick label formatting function
203

204
// Example tick formatter
205
const tickFormatter = (value: number) => {
206
  if (value >= 1000) return `${value / 1000}K`;
207
  return value.toString();
208
};
209
```
210

211
### Range and Scale
212

213
Define the value range and scale for gauge measurements.
214

215
```typescript { .api }
216
// Range configuration
217
@Input() min: number = 0;     // Minimum gauge value
218
@Input() max: number = 100;   // Maximum gauge value
219
@Input() units: string = '';  // Unit label (e.g., '%', 'rpm', 'mph')
220

221
// The gauge automatically scales the input value to fit within the range
222
// Values outside the range are clamped to min/max bounds
223
```
224

225
## Supporting Components
226

227
```typescript { .api }
228
// Gauge arc component for rendering the gauge background and value arc
229
@Component({ selector: 'g[ngx-charts-gauge-arc]' })
230
export class GaugeArcComponent {
231
  @Input() backgroundArc: any;
232
  @Input() valueArc: any;
233
  @Input() cornerRadius: number;
234
  @Input() colors: any;
235
  @Input() isActive: boolean = false;
236
  @Input() tooltipDisabled: boolean = false;
237
  @Input() valueFormatting: any;
238
  @Input() tooltipTemplate: TemplateRef<any>;
239
  @Input() animations: boolean = true;
240
  
241
  @Output() select: EventEmitter<any> = new EventEmitter();
242
  @Output() activate: EventEmitter<any> = new EventEmitter();
243
  @Output() deactivate: EventEmitter<any> = new EventEmitter();
244
}
245

246
// Gauge axis component for rendering tick marks and labels
247
@Component({ selector: 'g[ngx-charts-gauge-axis]' })
248
export class GaugeAxisComponent {
249
  @Input() bigSegments: any[];
250
  @Input() smallSegments: any[];
251
  @Input() min: number;
252
  @Input() max: number;
253
  @Input() angleSpan: number;
254
  @Input() startAngle: number;
255
  @Input() radius: number;
256
  @Input() valueScale: any;
257
  @Input() tickFormatting: any;
258
}
259
```
260

261
## Value Formatting
262

263
```typescript { .api }
264
// Value formatting function type
265
type ValueFormatting = (value: number) => string;
266

267
// Common formatters for different use cases
268
const percentFormatter: ValueFormatting = (value) => `${value.toFixed(1)}%`;
269
const currencyFormatter: ValueFormatting = (value) => `$${value.toLocaleString()}`;
270
const decimalFormatter: ValueFormatting = (value) => value.toFixed(2);
271
const integerFormatter: ValueFormatting = (value) => Math.round(value).toString();
272
const unitFormatter = (unit: string): ValueFormatting => (value) => `${value} ${unit}`;
273

274
// Custom formatting with thresholds
275
const thresholdFormatter: ValueFormatting = (value) => {
276
  if (value >= 1000000) return `${(value / 1000000).toFixed(1)}M`;
277
  if (value >= 1000) return `${(value / 1000).toFixed(1)}K`;
278
  return value.toString();
279
};
280
```
281

282
## Color Schemes and Thresholds
283

284
```typescript { .api }
285
// Gauge supports standard color schemes plus threshold-based coloring
286
@Input() colorScheme: any;
287
@Input() customColors: any;
288

289
// Example threshold-based coloring
290
const gaugeColorScheme = {
291
  domain: ['#5AA454', '#E44D25', '#CFC0BB', '#7aa3e5']
292
};
293

294
// Custom colors for specific value ranges
295
const customGaugeColors = [
296
  { name: 'Low', value: '#5AA454' },      // 0-30: Green
297
  { name: 'Medium', value: '#FFAE42' },   // 30-70: Orange  
298
  { name: 'High', value: '#E44D25' }      // 70-100: Red
299
];
300
```
301

302
## Multi-Value Gauges
303

304
```typescript { .api }
305
// Gauges can display multiple values using array input
306
interface MultiValueGaugeData {
307
  name: string;
308
  value: number;
309
  min?: number;
310
  max?: number;
311
}
312

313
// Example multi-value gauge data
314
const multiGaugeData: MultiValueGaugeData[] = [
315
  { name: 'CPU', value: 65, max: 100 },
316
  { name: 'Memory', value: 42, max: 100 },
317
  { name: 'Disk', value: 89, max: 100 }
318
];
319
```
320

321
## Advanced Features
322

323
### Previous Value Comparison
324

325
Linear gauges support displaying previous values for trend indication.
326

327
```typescript { .api }
328
// Previous value comparison (linear gauge only)
329
@Input() previousValue: number;
330

331
// Automatically shows trend indicator (increase/decrease)
332
// Renders subtle background bar showing previous position
333
```
334

335
### Animation Control
336

337
```typescript { .api }
338
// Animation configuration
339
@Input() animations: boolean = true;
340

341
// When enabled, provides smooth transitions for:
342
// - Value changes
343
// - Arc drawing animations
344
// - Color transitions
345
// - Scale updates
346
```
347

348
### Responsive Behavior
349

350
```typescript { .api }
351
// Margin configuration for responsive layout
352
@Input() margin: number[] = [10, 20, 10, 20]; // [top, right, bottom, left]
353

354
// Gauges automatically scale to fit container while maintaining aspect ratio
355
// Text and tick sizes adjust based on available space
356
```
357

358
## Data Structures
359

360
```typescript { .api }
361
// Gauge data structure
362
interface GaugeData extends DataItem {
363
  min?: number;  // Override global min for this value
364
  max?: number;  // Override global max for this value
365
}
366

367
// Gauge supports both single and multi-value datasets
368
type GaugeDataSet = GaugeData | GaugeData[];
369
```
370

371
## Accessibility
372

373
```typescript { .api }
374
// ARIA support for screen readers
375
@Input() ariaLabel: string = 'gauge chart';
376

377
// Automatically provides:
378
// - Value announcements
379
// - Range descriptions  
380
// - Progress indicators
381
// - Keyboard navigation support
382
```
383

384
## Use Cases
385

386
Gauge charts are ideal for:
387

388
- **Performance Metrics**: CPU usage, memory consumption, disk space
389
- **Progress Indicators**: Task completion, loading progress, goal achievement
390
- **KPI Dashboards**: Sales targets, customer satisfaction scores, efficiency ratings
391
- **Monitoring Systems**: Temperature readings, pressure gauges, speed indicators
392
- **Quality Metrics**: Test coverage, uptime percentages, error rates