0
# Pie Charts
1

2
Circular chart components for displaying part-to-whole relationships with support for advanced features, grid layouts, and donut configurations.
3

4
## Capabilities
5

6
### Pie Chart
7

8
Standard pie chart for displaying proportional data as slices of a circle.
9

10
```typescript { .api }
11
@Component({ selector: 'ngx-charts-pie-chart' })
12
export class PieChartComponent {
13
  @Input() results: SingleSeries;
14
  @Input() legend: boolean = false;
15
  @Input() legendTitle: string = 'Legend';
16
  @Input() legendPosition: LegendPosition = LegendPosition.Right;
17
  @Input() explodeSlices: boolean = false;
18
  @Input() labels: boolean = false;
19
  @Input() doughnut: boolean = false;
20
  @Input() arcWidth: number = 0.25;
21
  @Input() gradient: boolean = false;
22
  @Input() activeEntries: any[] = [];
23
  @Input() scheme: any;
24
  @Input() customColors: any;
25
  @Input() animations: boolean = true;
26
  @Input() trimLabels: boolean = true;
27
  @Input() maxLabelLength: number = 10;
28
  @Input() labelFormatting: any;
29
  @Input() tooltipDisabled: boolean = false;
30
  @Input() tooltipTemplate: TemplateRef<any>;
31
  @Input() tooltipText: any;
32
  @Input() ariaLabel: string = 'pie chart';
33
  
34
  @Output() select: EventEmitter<DataItem> = new EventEmitter();
35
  @Output() activate: EventEmitter<DataItem> = new EventEmitter();
36
  @Output() deactivate: EventEmitter<DataItem> = new EventEmitter();
37
  @Output() dblclick: EventEmitter<DataItem> = new EventEmitter();
38
}
39
```
40

41
**Usage Examples:**
42

43
```typescript
44
import { Component } from '@angular/core';
45

46
@Component({
47
  selector: 'app-pie-chart',
48
  template: `
49
    <ngx-charts-pie-chart
50
      [results]="pieData"
51
      [legend]="true"
52
      [explodeSlices]="false"
53
      [labels]="true"
54
      [doughnut]="false"
55
      [gradient]="true"
56
      [maxLabelLength]="15"
57
      (select)="onSelect($event)">
58
    </ngx-charts-pie-chart>
59
  `
60
})
61
export class PieChartComponent {
62
  pieData = [
63
    { name: 'Desktop', value: 8940000 },
64
    { name: 'Mobile', value: 5000000 },
65
    { name: 'Tablet', value: 2000000 },
66
    { name: 'Other', value: 1000000 }
67
  ];
68

69
  onSelect(event: any): void {
70
    console.log('Selected slice:', event);
71
  }
72
}
73
```
74

75
### Advanced Pie Chart
76

77
Enhanced pie chart with additional features and customization options.
78

79
```typescript { .api }
80
@Component({ selector: 'ngx-charts-advanced-pie-chart' })
81
export class AdvancedPieChartComponent {
82
  @Input() results: SingleSeries;
83
  @Input() gradient: boolean = false;
84
  @Input() activeEntries: any[] = [];
85
  @Input() scheme: any;
86
  @Input() customColors: any;
87
  @Input() animations: boolean = true;
88
  @Input() tooltipDisabled: boolean = false;
89
  @Input() tooltipTemplate: TemplateRef<any>;
90
  @Input() tooltipText: any;
91
  @Input() valueFormatting: any;
92
  @Input() nameFormatting: any;
93
  @Input() percentFormatting: any;
94
  @Input() ariaLabel: string = 'advanced pie chart';
95
  
96
  @Output() select: EventEmitter<DataItem> = new EventEmitter();
97
  @Output() activate: EventEmitter<DataItem> = new EventEmitter();
98
  @Output() deactivate: EventEmitter<DataItem> = new EventEmitter();
99
  @Output() dblclick: EventEmitter<DataItem> = new EventEmitter();
100
}
101
```
102

103
**Advanced Pie Usage:**
104

105
```typescript
106
@Component({
107
  template: `
108
    <ngx-charts-advanced-pie-chart
109
      [results]="data"
110
      [gradient]="true"
111
      [valueFormatting]="valueFormatter"
112
      [nameFormatting]="nameFormatter"
113
      [percentFormatting]="percentFormatter">
114
    </ngx-charts-advanced-pie-chart>
115
  `
116
})
117
export class AdvancedPieComponent {
118
  valueFormatter = (value: number) => `$${value.toLocaleString()}`;
119
  nameFormatter = (name: string) => name.toUpperCase();
120
  percentFormatter = (value: number) => `${value.toFixed(1)}%`;
121
}
122
```
123

124
### Pie Grid
125

126
Grid layout displaying multiple mini pie charts for comparing different datasets.
127

128
```typescript { .api }
129
@Component({ selector: 'ngx-charts-pie-grid' })
130
export class PieGridComponent {
131
  @Input() results: PieGridData[];
132
  @Input() designatedTotal: number;
133
  @Input() tooltipDisabled: boolean = false;
134
  @Input() tooltipTemplate: TemplateRef<any>;
135
  @Input() label: string = 'Total';
136
  @Input() minWidth: number = 150;
137
  @Input() activeEntries: any[] = [];
138
  @Input() scheme: any;
139
  @Input() customColors: any;
140
  @Input() animations: boolean = true;
141
  @Input() ariaLabel: string = 'pie grid';
142
  
143
  @Output() activate: EventEmitter<any> = new EventEmitter();
144
  @Output() deactivate: EventEmitter<any> = new EventEmitter();
145
  @Output() select: EventEmitter<DataItem> = new EventEmitter();
146
}
147
```
148

149
**Pie Grid Usage:**
150

151
```typescript
152
@Component({
153
  template: `
154
    <ngx-charts-pie-grid
155
      [results]="gridData"
156
      [designatedTotal]="1000000"
157
      [minWidth]="120"
158
      [label]="'Revenue'">
159
    </ngx-charts-pie-grid>
160
  `
161
})
162
export class PieGridComponent {
163
  gridData = [
164
    {
165
      name: 'Q1 2023',
166
      data: [
167
        { name: 'Product A', value: 89000 },
168
        { name: 'Product B', value: 56000 },
169
        { name: 'Product C', value: 45000 }
170
      ]
171
    },
172
    {
173
      name: 'Q2 2023', 
174
      data: [
175
        { name: 'Product A', value: 95000 },
176
        { name: 'Product B', value: 62000 },
177
        { name: 'Product C', value: 38000 }
178
      ]
179
    }
180
  ];
181
}
182
```
183

184
### Donut Chart Configuration
185

186
Transform pie charts into donut charts by adjusting the arc width.
187

188
```typescript { .api }
189
// Donut chart configuration
190
@Input() doughnut: boolean = false;
191
@Input() arcWidth: number = 0.25; // Thickness of the donut ring (0-1)
192

193
// When doughnut = true, creates hollow center
194
// arcWidth controls the thickness of the ring
195
// arcWidth = 1.0 creates full pie
196
// arcWidth = 0.1 creates thin ring
197
```
198

199
**Donut Chart Examples:**
200

201
```typescript
202
@Component({
203
  template: `
204
    <!-- Standard donut chart -->
205
    <ngx-charts-pie-chart
206
      [results]="data"
207
      [doughnut]="true"
208
      [arcWidth]="0.3">
209
    </ngx-charts-pie-chart>
210
    
211
    <!-- Thin ring donut -->
212
    <ngx-charts-pie-chart
213
      [results]="data"
214
      [doughnut]="true"
215
      [arcWidth]="0.15">
216
    </ngx-charts-pie-chart>
217
    
218
    <!-- Thick donut -->
219
    <ngx-charts-pie-chart
220
      [results]="data"
221
      [doughnut]="true"
222
      [arcWidth]="0.5">
223
    </ngx-charts-pie-chart>
224
  `
225
})
226
export class DonutChartComponent {
227
  // Donut charts use same data as pie charts
228
}
229
```
230

231
## Supporting Components
232

233
```typescript { .api }
234
// Pie series component for rendering pie slices
235
@Component({ selector: 'g[ngx-charts-pie-series]' })
236
export class PieSeriesComponent {
237
  @Input() colors: any;
238
  @Input() series: DataItem[];
239
  @Input() dims: ViewDimensions;
240
  @Input() innerRadius: number = 60;
241
  @Input() outerRadius: number = 80;
242
  @Input() explodeSlices: boolean;
243
  @Input() showLabels: boolean;
244
  @Input() gradient: boolean;
245
  @Input() activeEntries: any[];
246
  @Input() labelFormatting: any;
247
  @Input() trimLabels: boolean = true;
248
  @Input() maxLabelLength: number = 10;
249
  @Input() tooltipTemplate: TemplateRef<any>;
250
  @Input() tooltipDisabled: boolean = false;
251
  @Input() animations: boolean = true;
252
  
253
  @Output() select: EventEmitter<DataItem> = new EventEmitter();
254
  @Output() activate: EventEmitter<DataItem> = new EventEmitter();
255
  @Output() deactivate: EventEmitter<DataItem> = new EventEmitter();
256
  @Output() dblclick: EventEmitter<DataItem> = new EventEmitter();
257
}
258

259
// Individual pie arc component
260
@Component({ selector: 'g[ngx-charts-pie-arc]' })
261
export class PieArcComponent {
262
  @Input() fill: string;
263
  @Input() startAngle: number;
264
  @Input() endAngle: number;
265
  @Input() innerRadius: number;
266
  @Input() outerRadius: number;
267
  @Input() cornerRadius: number = 0;
268
  @Input() value: number;
269
  @Input() max: number;
270
  @Input() data: DataItem;
271
  @Input() explodeSlices: boolean;
272
  @Input() gradient: boolean;
273
  @Input() animate: boolean = true;
274
  @Input() pointerEvents: boolean = true;
275
  @Input() isActive: boolean = false;
276
  
277
  @Output() select: EventEmitter<DataItem> = new EventEmitter();
278
  @Output() activate: EventEmitter<DataItem> = new EventEmitter();
279
  @Output() deactivate: EventEmitter<DataItem> = new EventEmitter();
280
  @Output() dblclick: EventEmitter<DataItem> = new EventEmitter();
281
}
282

283
// Pie label component
284
@Component({ selector: 'g[ngx-charts-pie-label]' })
285
export class PieLabelComponent {
286
  @Input() data: DataItem;
287
  @Input() radius: number;
288
  @Input() label: string;
289
  @Input() color: string;
290
  @Input() max: number;
291
  @Input() value: number;
292
  @Input() explodeSlices: boolean;
293
  @Input() animations: boolean = true;
294
  @Input() labelTrim: boolean = true;
295
  @Input() labelTrimSize: number = 10;
296
  @Input() trimLabel: any;
297
}
298

299
// Pie grid series component
300
@Component({ selector: 'g[ngx-charts-pie-grid-series]' })
301
export class PieGridSeriesComponent {
302
  @Input() colors: any;
303
  @Input() data: PieGridData;
304
  @Input() innerRadius: number = 15;
305
  @Input() outerRadius: number = 80;
306
  @Input() animations: boolean = true;
307
  
308
  @Output() select: EventEmitter<DataItem> = new EventEmitter();
309
  @Output() activate: EventEmitter<any> = new EventEmitter();
310
  @Output() deactivate: EventEmitter<any> = new EventEmitter();
311
}
312
```
313

314
## Label Formatting
315

316
```typescript { .api }
317
// Label formatting function types
318
type LabelFormatting = (value: any) => string;
319
type ValueFormatting = (value: number) => string;
320
type NameFormatting = (name: string) => string; 
321
type PercentFormatting = (value: number) => string;
322

323
// Example formatters
324
const currencyFormatter: ValueFormatting = (value) => `$${value.toLocaleString()}`;
325
const percentFormatter: PercentFormatting = (value) => `${value.toFixed(1)}%`;
326
const shortNameFormatter: NameFormatting = (name) => name.length > 12 ? name.substring(0, 12) + '...' : name;
327

328
// Label trimming configuration
329
@Input() trimLabels: boolean = true;
330
@Input() maxLabelLength: number = 10;
331
```
332

333
## Exploding Slices
334

335
```typescript { .api }
336
// Explode slices configuration
337
@Input() explodeSlices: boolean = false;
338

339
// When enabled, separates pie slices with small gaps
340
// Creates visual emphasis and separation between segments
341
// Automatically calculates appropriate spacing based on chart size
342
```
343

344
## Data Structures
345

346
```typescript { .api }
347
// Pie chart data structure (single series)
348
type PieChartData = SingleSeries;
349

350
// Pie grid data structure
351
interface PieGridData {
352
  name: string;
353
  data: DataItem[];
354
}
355

356
// Pie arc calculation result
357
interface PieArc {
358
  startAngle: number;
359
  endAngle: number;
360
  value: number;
361
  data: DataItem;
362
  index: number;
363
}
364
```
365

366
## Advanced Customization
367

368
### Custom Colors
369

370
```typescript { .api }
371
// Custom color configuration
372
@Input() customColors: any;
373

374
// Example custom color scheme
375
const customColors = [
376
  { name: 'Desktop', value: '#1f77b4' },
377
  { name: 'Mobile', value: '#ff7f0e' },
378
  { name: 'Tablet', value: '#2ca02c' }
379
];
380
```
381

382
### Tooltip Customization
383

384
```typescript { .api }
385
// Custom tooltip template
386
@Input() tooltipTemplate: TemplateRef<any>;
387
@Input() tooltipText: any;
388

389
// Default tooltip displays name and value
390
// Custom templates allow full control over tooltip content and styling
391
```
392

393
**Custom Tooltip Example:**
394

395
```typescript
396
@Component({
397
  template: `
398
    <ngx-charts-pie-chart
399
      [results]="data"
400
      [tooltipTemplate]="tooltipTemplate">
401
    </ngx-charts-pie-chart>
402
    
403
    <ng-template #tooltipTemplate let-model="model">
404
      <div class="custom-tooltip">
405
        <strong>{{ model.name }}</strong><br>
406
        Value: {{ model.value | currency }}<br>
407
        Percentage: {{ model.percent | percent:'1.1-1' }}
408
      </div>
409
    </ng-template>
410
  `
411
})
412
export class CustomTooltipPieComponent { }
413
```
414

415
## Accessibility
416

417
All pie chart components include ARIA support for screen readers:
418

419
```typescript { .api }
420
@Input() ariaLabel: string = 'pie chart';
421

422
// Automatically generates appropriate ARIA labels for slices
423
// Supports keyboard navigation through chart elements
424
// Provides meaningful descriptions for assistive technologies
425
```