0
# Configuration System
1

2
ng2-charts provides a provider-based configuration system for registering Chart.js components and setting global defaults. This system is essential for proper Chart.js integration and enables bundle size optimization.
3

4
## Capabilities
5

6
### Provider Configuration
7

8
Main function for configuring ng2-charts in Angular applications.
9

10
```typescript { .api }
11
/**
12
 * Provides configuration for ng2-charts
13
 * Merges multiple configurations and creates Angular provider
14
 * @param configurations - Array of configuration objects to merge
15
 * @returns Angular provider for dependency injection
16
 */
17
function provideCharts(...configurations: readonly NgChartsConfiguration[]): Provider;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
// In main.ts (standalone application)
24
import { bootstrapApplication } from '@angular/platform-browser';
25
import { provideCharts, withDefaultRegisterables } from 'ng2-charts';
26
import { AppComponent } from './app/app.component';
27

28
bootstrapApplication(AppComponent, {
29
  providers: [
30
    provideCharts(withDefaultRegisterables())
31
  ]
32
}).catch(err => console.error(err));
33

34
// With custom registerables for bundle optimization
35
import { BarController, CategoryScale, LinearScale, BarElement, Title, Tooltip, Legend } from 'chart.js';
36
import { provideCharts } from 'ng2-charts';
37
import { AppComponent } from './app/app.component';
38

39
bootstrapApplication(AppComponent, {
40
  providers: [
41
    provideCharts({
42
      registerables: [BarController, CategoryScale, LinearScale, BarElement, Title, Tooltip, Legend]
43
    })
44
  ]
45
});
46
```
47

48
```typescript
49
// In NgModule (traditional application)
50
import { NgModule } from '@angular/core';
51
import { provideCharts, withDefaultRegisterables } from 'ng2-charts';
52
import { AppComponent } from './app/app.component';
53

54
@NgModule({
55
  providers: [
56
    provideCharts(withDefaultRegisterables())
57
  ],
58
  bootstrap: [AppComponent]
59
})
60
export class AppModule {}
61
```
62

63
### Default Registerables
64

65
Convenience function that provides all default Chart.js components plus additional ones.
66

67
```typescript { .api }
68
/**
69
 * Provides all default Chart.js registerables plus additional ones
70
 * Includes all controllers, scales, elements, and plugins from Chart.js
71
 * @param registerables - Additional registerables to include
72
 * @returns Configuration object with all registerables
73
 */
74
function withDefaultRegisterables(...registerables: ChartComponentLike[]): NgChartsConfiguration;
75
```
76

77
**Usage Examples:**
78

79
```typescript
80
import { provideCharts, withDefaultRegisterables } from 'ng2-charts';
81
import { MatrixController, MatrixElement } from 'chartjs-chart-matrix';
82

83
// Add custom chart type to default registerables
84
bootstrapApplication(AppComponent, {
85
  providers: [
86
    provideCharts(withDefaultRegisterables(MatrixController, MatrixElement))
87
  ]
88
});
89
```
90

91
### Configuration Interface
92

93
Configuration object structure for ng2-charts.
94

95
```typescript { .api }
96
/**
97
 * Configuration interface for ng2-charts
98
 */
99
interface NgChartsConfiguration {
100
  /** 
101
   * Chart.js registerables (controllers, scales, elements, plugins)
102
   * Used with Chart.register() internally
103
   */
104
  registerables?: readonly ChartComponentLike[];
105
  
106
  /** 
107
   * Default Chart.js configuration options
108
   * Applied globally using Chart.defaults.set()
109
   */
110
  defaults?: DeepPartial<Defaults>;
111
}
112
```
113

114
### Configuration Token
115

116
Injection token for accessing ng2-charts configuration.
117

118
```typescript { .api }
119
/**
120
 * Injection token for ng2-charts configuration
121
 * Used internally by BaseChartDirective to access configuration
122
 */
123
const NG_CHARTS_CONFIGURATION: InjectionToken<NgChartsConfiguration>;
124
```
125

126
## Bundle Optimization
127

128
For production applications, you can reduce bundle size by registering only the Chart.js components you need:
129

130
### Minimal Bar Chart Configuration
131

132
```typescript
133
import { 
134
  BarController, 
135
  CategoryScale, 
136
  LinearScale, 
137
  BarElement, 
138
  Title, 
139
  Tooltip, 
140
  Legend 
141
} from 'chart.js';
142
import { provideCharts } from 'ng2-charts';
143

144
// Only includes components needed for bar charts
145
const barChartConfig = {
146
  registerables: [
147
    BarController,    // Bar chart controller
148
    CategoryScale,    // X-axis scale
149
    LinearScale,      // Y-axis scale  
150
    BarElement,       // Bar visual element
151
    Title,            // Chart title plugin
152
    Tooltip,          // Tooltip plugin
153
    Legend            // Legend plugin
154
  ]
155
};
156

157
bootstrapApplication(AppComponent, {
158
  providers: [
159
    provideCharts(barChartConfig)
160
  ]
161
});
162
```
163

164
### Multiple Chart Types Configuration
165

166
```typescript
167
import { 
168
  BarController, 
169
  LineController,
170
  PieController,
171
  CategoryScale, 
172
  LinearScale,
173
  RadialLinearScale,
174
  BarElement,
175
  LineElement,
176
  PointElement,
177
  ArcElement,
178
  Title, 
179
  Tooltip, 
180
  Legend 
181
} from 'chart.js';
182

183
const multiChartConfig = {
184
  registerables: [
185
    // Controllers
186
    BarController,
187
    LineController, 
188
    PieController,
189
    // Scales
190
    CategoryScale,
191
    LinearScale,
192
    RadialLinearScale,
193
    // Elements
194
    BarElement,
195
    LineElement,
196
    PointElement,
197
    ArcElement,
198
    // Plugins
199
    Title,
200
    Tooltip,
201
    Legend
202
  ]
203
};
204
```
205

206
## Global Defaults Configuration
207

208
Set global defaults that apply to all charts in your application:
209

210
```typescript
211
import { provideCharts, withDefaultRegisterables } from 'ng2-charts';
212

213
const globalConfig = {
214
  defaults: {
215
    responsive: true,
216
    maintainAspectRatio: false,
217
    plugins: {
218
      legend: {
219
        display: true,
220
        position: 'top' as const
221
      },
222
      tooltip: {
223
        enabled: true,
224
        mode: 'index' as const,
225
        intersect: false
226
      }
227
    },
228
    scales: {
229
      x: {
230
        display: true,
231
        grid: {
232
          display: false
233
        }
234
      },
235
      y: {
236
        display: true,
237
        beginAtZero: true
238
      }
239
    }
240
  }
241
};
242

243
bootstrapApplication(AppComponent, {
244
  providers: [
245
    provideCharts(withDefaultRegisterables(), globalConfig)
246
  ]
247
});
248
```
249

250
## Advanced Configuration
251

252
### Multiple Configuration Merging
253

254
```typescript
255
import { provideCharts, withDefaultRegisterables } from 'ng2-charts';
256

257
const baseConfig = {
258
  defaults: {
259
    responsive: true,
260
    maintainAspectRatio: false
261
  }
262
};
263

264
const themeConfig = {
265
  defaults: {
266
    color: '#333',
267
    plugins: {
268
      legend: {
269
        labels: {
270
          color: '#333'
271
        }
272
      }
273
    }
274
  }
275
};
276

277
// Configurations are merged in order
278
bootstrapApplication(AppComponent, {
279
  providers: [
280
    provideCharts(
281
      withDefaultRegisterables(),
282
      baseConfig,
283
      themeConfig
284
    )
285
  ]
286
});
287
```
288

289
### Custom Plugin Registration
290

291
```typescript
292
import { provideCharts, withDefaultRegisterables } from 'ng2-charts';
293

294
// Custom plugin example
295
const customPlugin = {
296
  id: 'customPlugin',
297
  beforeDraw: (chart: any) => {
298
    // Custom plugin logic
299
  }
300
};
301

302
bootstrapApplication(AppComponent, {
303
  providers: [
304
    provideCharts(
305
      withDefaultRegisterables(customPlugin),
306
      {
307
        defaults: {
308
          plugins: {
309
            customPlugin: {
310
              enabled: true
311
            }
312
          }
313
        }
314
      }
315
    )
316
  ]
317
});
318
```