0
# NGX Charts
1

2
NGX Charts is a declarative charting framework for Angular applications that renders charts using SVG elements through Angular's binding system. Built on D3.js, it provides extensive chart type support with full TypeScript integration, server-side rendering compatibility, and real-time data capabilities without wrapping existing chart libraries.
3

4
## Package Information
5

6
- **Package Name**: @swimlane/ngx-charts
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @swimlane/ngx-charts`
10

11
## Core Imports
12

13
```typescript
14
import { NgxChartsModule } from '@swimlane/ngx-charts';
15
import { 
16
  BarVerticalComponent, 
17
  LineChartComponent, 
18
  PieChartComponent 
19
} from '@swimlane/ngx-charts';
20
```
21

22
For individual chart modules:
23

24
```typescript
25
import { BarChartModule } from '@swimlane/ngx-charts';
26
import { LineChartModule } from '@swimlane/ngx-charts';
27
import { PieChartModule } from '@swimlane/ngx-charts';
28
```
29

30
## Basic Usage
31

32
### Module Setup
33

34
```typescript
35
import { NgModule } from '@angular/core';
36
import { NgxChartsModule } from '@swimlane/ngx-charts';
37

38
@NgModule({
39
  imports: [NgxChartsModule],
40
  // ... rest of module
41
})
42
export class AppModule { }
43
```
44

45
### Simple Bar Chart
46

47
```typescript
48
import { Component } from '@angular/core';
49

50
@Component({
51
  selector: 'app-chart',
52
  template: `
53
    <ngx-charts-bar-vertical
54
      [results]="data"
55
      [xAxis]="true"
56
      [yAxis]="true"
57
      [legend]="true"
58
      [showXAxisLabel]="true"
59
      [showYAxisLabel]="true"
60
      xAxisLabel="Categories"
61
      yAxisLabel="Values">
62
    </ngx-charts-bar-vertical>
63
  `
64
})
65
export class ChartComponent {
66
  data = [
67
    { name: 'Category A', value: 30 },
68
    { name: 'Category B', value: 45 },
69
    { name: 'Category C', value: 25 }
70
  ];
71
}
72
```
73

74
## Architecture
75

76
NGX Charts is built around several key components:
77

78
- **Chart Components**: Specialized chart types (bars, lines, pies, etc.) that handle rendering and interaction
79
- **Common Infrastructure**: Shared axes, legends, tooltips, and utility components
80
- **Data Models**: TypeScript interfaces defining chart data structures and configuration options
81
- **D3 Integration**: Leverages D3.js for mathematical functions, scales, and shape generation
82
- **Angular Integration**: Native Angular components with full change detection and lifecycle support
83

84
## Capabilities
85

86
### Bar Charts
87

88
Comprehensive bar chart variants including vertical, horizontal, stacked, grouped, and normalized configurations with customizable styling and data labels.
89

90
```typescript { .api }
91
// Main bar chart components
92
@Component({ selector: 'ngx-charts-bar-vertical' })
93
export class BarVerticalComponent extends BaseChartComponent {
94
  @Input() results: SingleSeries;
95
  @Input() legend: boolean = false;
96
  @Input() xAxis: boolean;
97
  @Input() yAxis: boolean;
98
  @Input() showXAxisLabel: boolean;
99
  @Input() showYAxisLabel: boolean;
100
  @Input() xAxisLabel: string;
101
  @Input() yAxisLabel: string;
102
  @Input() barPadding: number = 8;
103
  @Input() roundDomains: boolean = false;
104
  @Input() trimXAxisTicks: boolean = true;
105
  @Input() trimYAxisTicks: boolean = true;
106
  @Input() rotateXAxisTicks: boolean = true;
107
  @Input() tooltipDisabled: boolean = false;
108
  @Input() gradient: boolean;
109
  @Output() activate: EventEmitter<any>;
110
  @Output() deactivate: EventEmitter<any>;
111
}
112

113
@Component({ selector: 'ngx-charts-bar-horizontal' })
114
export class BarHorizontalComponent extends BaseChartComponent {
115
  @Input() results: SingleSeries;
116
  @Input() legend: boolean = false;
117
  @Input() xAxis: boolean;
118
  @Input() yAxis: boolean;
119
  @Input() trimXAxisTicks: boolean = true;
120
  @Input() trimYAxisTicks: boolean = true;
121
  @Output() activate: EventEmitter<any>;
122
  @Output() deactivate: EventEmitter<any>;
123
}
124
```
125

126
[Bar Charts](./bar-charts.md)
127

128
### Line Charts
129

130
Line chart visualization for trend analysis with curve interpolation, multi-series support, and timeline features.
131

132
```typescript { .api }
133
@Component({ selector: 'ngx-charts-line-chart' })
134
export class LineChartComponent extends BaseChartComponent {
135
  @Input() results: MultiSeries;
136
  @Input() legend: boolean;
137
  @Input() xAxis: boolean;
138
  @Input() yAxis: boolean;
139
  @Input() curve: any = curveLinear;
140
  @Input() timeline: boolean;
141
  @Input() showGridLines: boolean = true;
142
  @Input() referenceLines: any;
143
  @Input() trimXAxisTicks: boolean = true;
144
  @Input() trimYAxisTicks: boolean = true;
145
  @Input() tooltipDisabled: boolean = false;
146
  @Output() activate: EventEmitter<any>;
147
  @Output() deactivate: EventEmitter<any>;
148
}
149
```
150

151
[Line Charts](./line-charts.md)
152

153
### Area Charts
154

155
Area chart components for visualizing cumulative data trends with stacked and normalized variants.
156

157
```typescript { .api }
158
@Component({ selector: 'ngx-charts-area-chart' })
159
export class AreaChartComponent extends BaseChartComponent {
160
  @Input() results: MultiSeries;
161
  @Input() legend: boolean = false;
162
  @Input() xAxis: boolean = false;
163
  @Input() yAxis: boolean = false;
164
  @Input() curve: CurveFactory = curveLinear;
165
  @Input() gradient: boolean;
166
  @Input() baseValue: any = 'auto';
167
  @Input() autoScale: boolean = false;
168
  @Input() timeline: boolean = false;
169
  @Input() trimXAxisTicks: boolean = true;
170
  @Input() trimYAxisTicks: boolean = true;
171
  @Input() tooltipDisabled: boolean = false;
172
  @Output() activate: EventEmitter<any>;
173
  @Output() deactivate: EventEmitter<any>;
174
}
175
```
176

177
[Area Charts](./area-charts.md)
178

179
### Pie Charts
180

181
Circular chart components for part-to-whole relationships with advanced features and grid layouts.
182

183
```typescript { .api }
184
@Component({ selector: 'ngx-charts-pie-chart' })
185
export class PieChartComponent {
186
  @Input() results: SingleSeries;
187
  @Input() legend: boolean;
188
  @Input() explodeSlices: boolean;
189
  @Input() labels: boolean;
190
  @Input() doughnut: boolean;
191
  @Input() arcWidth: number;
192
  @Output() select: EventEmitter<any>;
193
  @Output() activate: EventEmitter<any>;
194
  @Output() deactivate: EventEmitter<any>;
195
}
196
```
197

198
[Pie Charts](./pie-charts.md)
199

200
### Gauge Charts
201

202
Gauge components for displaying single values with customizable ranges and styling.
203

204
```typescript { .api }
205
@Component({ selector: 'ngx-charts-gauge' })
206
export class GaugeComponent {
207
  @Input() results: SingleSeries;
208
  @Input() min: number;
209
  @Input() max: number;
210
  @Input() units: string;
211
  @Input() bigSegments: number;
212
  @Input() smallSegments: number;
213
  @Input() showAxis: boolean;
214
  @Input() startAngle: number;
215
  @Input() angleSpan: number;
216
  @Output() activate: EventEmitter<any>;
217
  @Output() deactivate: EventEmitter<any>;
218
}
219
```
220

221
[Gauge Charts](./gauge-charts.md)
222

223
### Other Chart Types
224

225
Additional specialized chart types for specific data visualization needs.
226

227
```typescript { .api }
228
// Bubble chart for three-dimensional data
229
@Component({ selector: 'ngx-charts-bubble-chart' })
230
export class BubbleChartComponent {
231
  @Input() results: BubbleChartSeries[];
232
  @Input() minRadius: number;
233
  @Input() maxRadius: number;
234
}
235

236
// Heat map for matrix data
237
@Component({ selector: 'ngx-charts-heat-map' })
238
export class HeatMapComponent {
239
  @Input() results: MultiSeries;
240
  @Input() gradient: boolean;
241
}
242

243
// Tree map for hierarchical data
244
@Component({ selector: 'ngx-charts-tree-map' })
245
export class TreeMapComponent {
246
  @Input() results: TreeMapDataItem[];
247
}
248

249
// Number cards for KPI display
250
@Component({ selector: 'ngx-charts-number-card' })
251
export class NumberCardComponent {
252
  @Input() results: SingleSeries;
253
  @Input() cardColor: string;
254
  @Input() textColor: string;
255
}
256

257
// Box charts for statistical data
258
@Component({ selector: 'ngx-charts-box-chart' })
259
export class BoxChartComponent extends BaseChartComponent {
260
  @Input() results: BoxChartMultiSeries;
261
  @Input() legend: boolean = false;
262
  @Input() strokeColor: string = '#FFFFFF';
263
  @Input() strokeWidth: number = 2;
264
  @Input() roundEdges: boolean = true;
265
  @Input() tooltipDisabled: boolean = false;
266
}
267

268
// Polar charts for multivariate data
269
@Component({ selector: 'ngx-charts-polar-chart' })
270
export class PolarChartComponent {
271
  @Input() results: MultiSeries;
272
  @Input() legend: boolean;
273
  @Input() curve: CurveFactory;
274
}
275

276
// Sankey diagrams for flow visualization
277
@Component({ selector: 'ngx-charts-sankey' })
278
export class SankeyComponent {
279
  @Input() results: SankeyData;
280
  @Input() nodeWidth: number;
281
  @Input() nodePadding: number;
282
}
283
```
284

285
[Other Chart Types](./other-charts.md)
286

287
## Data Models
288

289
```typescript { .api }
290
// Core data interfaces
291
interface DataItem {
292
  name: StringOrNumberOrDate;
293
  value: number;
294
  extra?: any;
295
  min?: number;
296
  max?: number;
297
  label?: string;
298
}
299

300
interface Series {
301
  name: StringOrNumberOrDate;
302
  series: DataItem[];
303
}
304

305
// Chart data types
306
type SingleSeries = DataItem[];
307
type MultiSeries = Series[];
308
type StringOrNumberOrDate = string | number | Date;
309

310
// Bubble chart specific
311
interface BubbleChartDataItem {
312
  name: StringOrNumberOrDate;
313
  x: StringOrNumberOrDate;
314
  y: StringOrNumberOrDate;
315
  r: number;
316
  extra?: any;
317
}
318

319
interface BubbleChartSeries {
320
  name: StringOrNumberOrDate;
321
  series: BubbleChartDataItem[];
322
}
323

324
// Tree map specific  
325
interface TreeMapDataItem {
326
  name: StringOrNumberOrDate;
327
  size?: number;
328
  children?: TreeMapDataItem[];
329
  extra?: any;
330
}
331

332
// Box chart specific
333
interface IBoxModel {
334
  name: StringOrNumberOrDate;
335
  value: number;
336
  q1: number;
337
  q3: number;
338
  median: number;
339
  whiskers: [number, number];
340
  outliers: number[];
341
}
342

343
interface BoxChartSeries {
344
  name: StringOrNumberOrDate;
345
  series: IBoxModel[];
346
}
347

348
// Sankey diagram specific
349
interface SankeyData {
350
  nodes: Array<{ id: string; label?: string }>;
351
  links: Array<{
352
    source: string;
353
    target: string;
354
    value: number;
355
  }>;
356
}
357
```
358

359
## Base Chart Component
360

361
All chart components extend the `BaseChartComponent` which provides common functionality and inputs:
362

363
```typescript { .api }
364
@Component({ selector: 'base-chart' })
365
export class BaseChartComponent implements OnChanges, AfterViewInit, OnDestroy, OnInit {
366
  @Input() results: any;
367
  @Input() view: [number, number];
368
  @Input() scheme: string | Color = 'cool';
369
  @Input() schemeType: ScaleType = ScaleType.Ordinal;
370
  @Input() customColors: any;
371
  @Input() animations: boolean = true;
372
  
373
  @Output() select = new EventEmitter();
374
  
375
  width: number;
376
  height: number;
377
}
378
```
379

380
This base component handles:
381
- Automatic resizing and responsive behavior
382
- Data cloning and change detection
383
- Common chart properties (view, scheme, animations)
384
- Date formatting utilities
385
- Visibility detection for performance optimization
386

387
## Common Configuration
388

389
```typescript { .api }
390
// Scale types for different data types
391
enum ScaleType {
392
  Time = 'time',
393
  Linear = 'linear',
394
  Ordinal = 'ordinal',
395
  Quantile = 'quantile'
396
}
397

398
// Legend configuration
399
enum LegendPosition {
400
  Right = 'right',
401
  Below = 'below'
402
}
403

404
// View dimensions interface
405
interface ViewDimensions {
406
  width: number;
407
  height: number;
408
  xOffset?: number;
409
  yOffset?: number;
410
}
411

412
// Color scheme interface
413
interface Color {
414
  name: string;
415
  selectable: boolean;
416
  group: ScaleType;
417
  domain: string[];
418
}
419
```
420

421
## Styling & Theming
422

423
NGX Charts provides extensive CSS-based customization through CSS variables and class-based styling. All chart elements can be styled using standard CSS approaches while maintaining SVG-based rendering performance.
424

425
[Styling & Theming](./styling-theming.md)