0
# ng2-charts
1

2
ng2-charts is a reactive, responsive Angular library that provides beautiful chart components based on Chart.js. It offers a single directive that supports 8 different chart types (line, bar, radar, pie, polar area, doughnut, bubble, and scatter) with dynamic theming capabilities, event handling, and flexible data binding options.
3

4
## Package Information
5

6
- **Package Name**: ng2-charts
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `ng add ng2-charts` or `npm install ng2-charts`
10
- **Peer Dependencies**: Angular 19.0.0+, Chart.js ^3.4.0 || ^4.0.0, RxJS ^6.5.3 || ^7.4.0
11

12
## Core Imports
13

14
```typescript
15
import { BaseChartDirective, ThemeService, provideCharts, withDefaultRegisterables, NgChartsConfiguration, NG_CHARTS_CONFIGURATION } from "ng2-charts";
16
import { ChartConfiguration, ChartData, ChartOptions, ChartType, ChartEvent, Plugin, UpdateMode } from "chart.js";
17
```
18

19
For CommonJS (if supported):
20

21
```javascript
22
const { BaseChartDirective, ThemeService, provideCharts, withDefaultRegisterables } = require("ng2-charts");
23
const { ChartConfiguration, ChartData, ChartOptions } = require("chart.js");
24
```
25

26
## Basic Usage
27

28
```typescript
29
import { Component } from '@angular/core';
30
import { BaseChartDirective } from 'ng2-charts';
31
import { ChartData, ChartOptions, ChartType } from 'chart.js';
32

33
@Component({
34
  selector: 'app-chart',
35
  template: `
36
    <canvas 
37
      baseChart
38
      [data]="chartData"
39
      [options]="chartOptions"
40
      [type]="chartType"
41
      (chartClick)="onChartClick($event)"
42
      (chartHover)="onChartHover($event)">
43
    </canvas>
44
  `,
45
  standalone: true,
46
  imports: [BaseChartDirective]
47
})
48
export class ChartComponent {
49
  chartType: ChartType = 'bar';
50
  
51
  chartData: ChartData = {
52
    labels: ['Red', 'Blue', 'Yellow', 'Green', 'Purple', 'Orange'],
53
    datasets: [{
54
      label: '# of Votes',
55
      data: [12, 19, 3, 5, 2, 3],
56
      backgroundColor: [
57
        'rgba(255, 99, 132, 0.2)',
58
        'rgba(54, 162, 235, 0.2)',
59
        'rgba(255, 205, 86, 0.2)',
60
        'rgba(75, 192, 192, 0.2)',
61
        'rgba(153, 102, 255, 0.2)',
62
        'rgba(255, 159, 64, 0.2)'
63
      ]
64
    }]
65
  };
66

67
  chartOptions: ChartOptions = {
68
    responsive: true,
69
    plugins: {
70
      legend: {
71
        display: true
72
      }
73
    }
74
  };
75

76
  onChartClick(event: any) {
77
    console.log('Chart clicked:', event);
78
  }
79

80
  onChartHover(event: any) {
81
    console.log('Chart hovered:', event);
82
  }
83
}
84
```
85

86
## Architecture
87

88
ng2-charts is built around several key components:
89

90
- **BaseChartDirective**: The main directive that wraps Chart.js functionality for Angular
91
- **Configuration System**: Provider-based configuration using `provideCharts` and `withDefaultRegisterables`
92
- **Theme Service**: Dynamic theming system for runtime color scheme changes
93
- **Event System**: Angular-style event emitters for chart interactions
94
- **Type Safety**: Full TypeScript integration with Chart.js types
95

96
## Capabilities
97

98
### Chart Directive
99

100
The main BaseChartDirective provides the core charting functionality with support for 8 chart types, reactive data binding, and Angular lifecycle integration.
101

102
```typescript { .api }
103
@Directive({
104
  selector: 'canvas[baseChart]',
105
  exportAs: 'base-chart',
106
  standalone: true
107
})
108
export class BaseChartDirective<TType extends ChartType = ChartType, TData = DefaultDataPoint<TType>, TLabel = unknown> implements OnDestroy, OnChanges {
109
  @Input() type: ChartConfiguration<TType, TData, TLabel>['type'];
110
  @Input() legend?: boolean;
111
  @Input() data?: ChartConfiguration<TType, TData, TLabel>['data'];
112
  @Input() options: ChartConfiguration<TType, TData, TLabel>['options'];
113
  @Input() plugins: Plugin<TType>[];
114
  @Input() labels?: ChartConfiguration<TType, TData, TLabel>['data']['labels'];
115
  @Input() datasets?: ChartConfiguration<TType, TData, TLabel>['data']['datasets'];
116
  
117
  @Output() chartClick: EventEmitter<{event?: ChartEvent; active?: object[]}>;
118
  @Output() chartHover: EventEmitter<{event: ChartEvent; active: object[]}>;
119
  
120
  ctx: string;
121
  chart?: Chart<TType, TData, TLabel>;
122
  
123
  constructor(element: ElementRef, zone: NgZone, themeService: ThemeService, config?: NgChartsConfiguration);
124
  
125
  ngOnChanges(changes: SimpleChanges): void;
126
  ngOnDestroy(): void;
127
  render(): Chart<TType, TData, TLabel>;
128
  update(mode?: UpdateMode): void;
129
  hideDataset(index: number, hidden: boolean): void;
130
  isDatasetHidden(index: number): boolean | undefined;
131
  toBase64Image(): string | undefined;
132
}
133
```
134

135
[Chart Directive](./chart-directive.md)
136

137
### Configuration System
138

139
Provider-based configuration system for registering Chart.js components and setting default options. Essential for proper Chart.js integration and bundle optimization.
140

141
```typescript { .api }
142
function provideCharts(...configurations: readonly NgChartsConfiguration[]): Provider;
143

144
function withDefaultRegisterables(...registerables: ChartComponentLike[]): NgChartsConfiguration;
145

146
interface NgChartsConfiguration {
147
  registerables?: readonly ChartComponentLike[];
148
  defaults?: DeepPartial<Defaults>;
149
}
150
```
151

152
[Configuration](./configuration.md)
153

154
### Dynamic Theming
155

156
Theme service for runtime color scheme changes and dynamic chart styling. Allows applications to update chart appearance based on user preferences or application state.
157

158
```typescript { .api }
159
@Injectable({
160
  providedIn: 'root'
161
})
162
export class ThemeService {
163
  colorschemesOptions: BehaviorSubject<ChartOptions | undefined>;
164
  
165
  setColorschemesOptions(options: ChartConfiguration['options']): void;
166
  getColorschemesOptions(): ChartConfiguration['options'];
167
}
168
```
169

170
[Dynamic Theming](./theming.md)
171

172
## Types
173

174
### Chart.js Types
175

176
These types are imported from Chart.js:
177

178
```typescript { .api }
179
type ChartType = 'line' | 'bar' | 'radar' | 'pie' | 'polarArea' | 'doughnut' | 'bubble' | 'scatter';
180
type UpdateMode = 'resize' | 'reset' | 'none' | 'hide' | 'show' | 'normal' | 'active';
181
type DefaultDataPoint<TType extends ChartType> = TType extends 'line' ? number | Point : TType extends 'bar' ? number : TType extends 'bubble' ? BubbleDataPoint : number;
182

183
interface ChartConfiguration<TType extends ChartType = ChartType, TData = DefaultDataPoint<TType>, TLabel = unknown> {
184
  type: TType;
185
  data: ChartData<TType, TData, TLabel>;
186
  options?: ChartOptions<TType>;
187
  plugins?: Plugin<TType>[];
188
}
189

190
interface ChartData<TType extends ChartType = ChartType, TData = DefaultDataPoint<TType>, TLabel = unknown> {
191
  labels?: TLabel[];
192
  datasets: ChartDataset<TType, TData>[];
193
}
194

195
interface Plugin<TType extends ChartType = ChartType> {
196
  id: string;
197
  [key: string]: any;
198
}
199

200
interface ChartComponentLike {
201
  id: string;
202
  [key: string]: any;
203
}
204

205
type DeepPartial<T> = {
206
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
207
};
208

209
interface Defaults {
210
  [key: string]: any;
211
}
212
```
213

214
### Event Types
215

216
```typescript { .api }
217
interface ChartEvent {
218
  type: string;
219
  native: Event | null;
220
  x: number | null;
221
  y: number | null;
222
}
223
```
224

225
### ng2-charts Configuration Types
226

227
```typescript { .api }
228
interface NgChartsConfiguration {
229
  registerables?: readonly ChartComponentLike[];
230
  defaults?: DeepPartial<Defaults>;
231
}
232

233
const NG_CHARTS_CONFIGURATION: InjectionToken<NgChartsConfiguration>;
234
```