0
# Chart Types
1

2
Plotly.js supports 48+ different chart types covering statistical, scientific, financial, geographic, and 3D visualizations. Each trace type has unique attributes and capabilities.
3

4
## Basic Chart Types
5

6
### Scatter Plots
7

8
The most versatile trace type supporting scatter plots, line charts, text charts, and bubble charts through mode variations.
9

10
```javascript { .api }
11
interface ScatterTrace {
12
  type: 'scatter';
13
  x?: number[] | string[] | Date[];
14
  y?: number[];
15
  mode?: 'markers' | 'lines' | 'text' | 'lines+markers' | 'lines+text' | 'markers+text' | 'lines+markers+text' | 'none';
16
  text?: string | string[];
17
  textposition?: 'top left' | 'top center' | 'top right' | 'middle left' | 'middle center' | 'middle right' | 'bottom left' | 'bottom center' | 'bottom right';
18
  line?: {
19
    color?: string;
20
    width?: number;
21
    dash?: 'solid' | 'dot' | 'dash' | 'longdash' | 'dashdot' | 'longdashdot';
22
    shape?: 'linear' | 'spline' | 'hv' | 'vh' | 'hvh' | 'vhv';
23
    smoothing?: number;
24
  };
25
  marker?: {
26
    color?: string | string[] | number[];
27
    size?: number | number[];
28
    symbol?: string | string[];
29
    opacity?: number | number[];
30
    line?: {
31
      color?: string | string[];
32
      width?: number | number[];
33
    };
34
  };
35
  fill?: 'none' | 'tozeroy' | 'tozerox' | 'tonexty' | 'tonextx' | 'toself' | 'tonext';
36
  fillcolor?: string;
37
}
38
```
39

40
**Usage Examples:**
41

42
```javascript
43
// Basic scatter plot
44
const scatter = {
45
  x: [1, 2, 3, 4, 5],
46
  y: [2, 4, 3, 5, 6],
47
  type: 'scatter',
48
  mode: 'markers',
49
  name: 'Data Points'
50
};
51

52
// Line chart
53
const line = {
54
  x: [1, 2, 3, 4, 5],
55
  y: [2, 4, 3, 5, 6],
56
  type: 'scatter',
57
  mode: 'lines',
58
  name: 'Trend Line'
59
};
60

61
// Bubble chart
62
const bubble = {
63
  x: [1, 2, 3, 4],
64
  y: [10, 11, 12, 13],
65
  type: 'scatter',
66
  mode: 'markers',
67
  marker: {
68
    size: [40, 60, 80, 100],
69
    color: ['red', 'blue', 'green', 'purple']
70
  },
71
  name: 'Bubble Chart'
72
};
73

74
// Area chart
75
const area = {
76
  x: [1, 2, 3, 4, 5],
77
  y: [2, 4, 3, 5, 6],
78
  type: 'scatter',
79
  mode: 'lines',
80
  fill: 'tozeroy',
81
  fillcolor: 'rgba(0,100,80,0.2)',
82
  name: 'Area Chart'
83
};
84
```
85

86
### Bar Charts
87

88
Horizontal and vertical bar charts with extensive customization options.
89

90
```javascript { .api }
91
interface BarTrace {
92
  type: 'bar';
93
  x?: string[] | number[];
94
  y?: number[];
95
  orientation?: 'v' | 'h';
96
  name?: string;
97
  text?: string | string[];
98
  textposition?: 'inside' | 'outside' | 'auto' | 'none';
99
  textangle?: number;
100
  insidetextanchor?: 'end' | 'middle' | 'start';
101
  marker?: {
102
    color?: string | string[] | number[];
103
    opacity?: number | number[];
104
    line?: {
105
      color?: string | string[];
106
      width?: number | number[];
107
    };
108
  };
109
  width?: number | number[];
110
  offset?: number | number[];
111
  base?: number | number[];
112
}
113
```
114

115
**Usage Examples:**
116

117
```javascript
118
// Vertical bar chart
119
const verticalBar = {
120
  x: ['A', 'B', 'C', 'D'],
121
  y: [20, 14, 25, 16],
122
  type: 'bar',
123
  name: 'Vertical Bars'
124
};
125

126
// Horizontal bar chart
127
const horizontalBar = {
128
  x: [20, 14, 25, 16],
129
  y: ['A', 'B', 'C', 'D'],
130
  type: 'bar',
131
  orientation: 'h',
132
  name: 'Horizontal Bars'
133
};
134

135
// Grouped bar chart
136
const group1 = {
137
  x: ['Q1', 'Q2', 'Q3', 'Q4'],
138
  y: [20, 14, 25, 16],
139
  type: 'bar',
140
  name: 'Series 1'
141
};
142

143
const group2 = {
144
  x: ['Q1', 'Q2', 'Q3', 'Q4'],
145
  y: [16, 18, 22, 19],
146
  type: 'bar',
147
  name: 'Series 2'
148
};
149

150
// Stacked bar chart (set barmode: 'stack' in layout)
151
```
152

153
### Pie Charts
154

155
Circular charts for showing proportional data with donut chart capability.
156

157
```javascript { .api }
158
interface PieTrace {
159
  type: 'pie';
160
  labels?: string[];
161
  values?: number[];
162
  hole?: number; // 0-1, creates donut chart
163
  sort?: boolean;
164
  direction?: 'clockwise' | 'counterclockwise';
165
  rotation?: number;
166
  pull?: number | number[]; // 0-1, explodes sectors
167
  textinfo?: 'label' | 'text' | 'value' | 'percent' | 'label+text' | 'label+value' | 'label+percent' | 'text+value' | 'text+percent' | 'value+percent' | 'label+text+value' | 'label+text+percent' | 'label+value+percent' | 'text+value+percent' | 'label+text+value+percent' | 'none';
168
  textposition?: 'inside' | 'outside' | 'auto' | 'none';
169
  marker?: {
170
    colors?: string[];
171
    line?: {
172
      color?: string | string[];
173
      width?: number | number[];
174
    };
175
  };
176
}
177
```
178

179
**Usage Examples:**
180

181
```javascript
182
// Basic pie chart
183
const pie = {
184
  labels: ['Oxygen', 'Hydrogen', 'Carbon', 'Nitrogen'],
185
  values: [4500, 2500, 1053, 500],
186
  type: 'pie',
187
  name: 'Elements'
188
};
189

190
// Donut chart
191
const donut = {
192
  labels: ['A', 'B', 'C'],
193
  values: [10, 20, 30],
194
  type: 'pie',
195
  hole: 0.4,
196
  name: 'Donut Chart'
197
};
198

199
// Exploded pie chart
200
const exploded = {
201
  labels: ['A', 'B', 'C', 'D'],
202
  values: [10, 15, 20, 25],
203
  type: 'pie',
204
  pull: [0, 0.1, 0, 0], // Explode second slice
205
  name: 'Exploded Pie'
206
};
207
```
208

209
## Statistical Charts
210

211
### Box Plots
212

213
Statistical distribution visualization showing quartiles, outliers, and whiskers.
214

215
```javascript { .api }
216
interface BoxTrace {
217
  type: 'box';
218
  x?: string[] | number[];
219
  y?: number[];
220
  orientation?: 'v' | 'h';
221
  boxpoints?: 'all' | 'outliers' | 'suspectedoutliers' | false;
222
  boxmean?: boolean | 'sd';
223
  whiskerwidth?: number;
224
  marker?: {
225
    color?: string;
226
    size?: number;
227
    symbol?: string;
228
    opacity?: number;
229
  };
230
  line?: {
231
    color?: string;
232
    width?: number;
233
  };
234
  fillcolor?: string;
235
}
236
```
237

238
### Violin Plots
239

240
Density distribution visualization combining box plot information with kernel density estimation.
241

242
```javascript { .api }
243
interface ViolinTrace {
244
  type: 'violin';
245
  x?: string[] | number[];
246
  y?: number[];
247
  orientation?: 'v' | 'h';
248
  side?: 'both' | 'positive' | 'negative';
249
  width?: number;
250
  points?: 'all' | 'outliers' | 'suspectedoutliers' | false;
251
  box?: {
252
    visible?: boolean;
253
    width?: number;
254
    fillcolor?: string;
255
    line?: {
256
      color?: string;
257
      width?: number;
258
    };
259
  };
260
  meanline?: {
261
    visible?: boolean;
262
    color?: string;
263
    width?: number;
264
  };
265
}
266
```
267

268
### Histograms
269

270
Distribution visualization for continuous data.
271

272
```javascript { .api }
273
interface HistogramTrace {
274
  type: 'histogram';
275
  x?: number[];
276
  y?: number[];
277
  orientation?: 'v' | 'h';
278
  histnorm?: '' | 'percent' | 'probability' | 'density' | 'probability density';
279
  histfunc?: 'count' | 'sum' | 'avg' | 'min' | 'max';
280
  cumulative?: {
281
    enabled?: boolean;
282
    direction?: 'increasing' | 'decreasing';
283
    currentbin?: 'include' | 'exclude' | 'half';
284
  };
285
  nbinsx?: number;
286
  nbinsy?: number;
287
  autobinx?: boolean;
288
  autobiny?: boolean;
289
}
290
```
291

292
## Scientific Charts
293

294
### Heatmaps
295

296
2D data visualization using color intensity to represent values.
297

298
```javascript { .api }
299
interface HeatmapTrace {
300
  type: 'heatmap';
301
  z: number[][];
302
  x?: string[] | number[];
303
  y?: string[] | number[];
304
  colorscale?: string | Array<[number, string]>;
305
  showscale?: boolean;
306
  zmin?: number;
307
  zmax?: number;
308
  zauto?: boolean;
309
  colorbar?: ColorbarConfig;
310
  xgap?: number;
311
  ygap?: number;
312
  zsmooth?: 'fast' | 'best' | false;
313
}
314
```
315

316
### Contour Plots
317

318
Contour lines showing areas of equal value in 2D data.
319

320
```javascript { .api }
321
interface ContourTrace {
322
  type: 'contour';
323
  z: number[][];
324
  x?: number[];
325
  y?: number[];
326
  colorscale?: string | Array<[number, string]>;
327
  showscale?: boolean;
328
  contours?: {
329
    start?: number;
330
    end?: number;
331
    size?: number;
332
    coloring?: 'fill' | 'heatmap' | 'lines' | 'none';
333
    showlines?: boolean;
334
    showlabels?: boolean;
335
  };
336
  line?: {
337
    color?: string;
338
    width?: number;
339
    dash?: string;
340
    smoothing?: number;
341
  };
342
}
343
```
344

345
## 3D Charts
346

347
### 3D Scatter Plots
348

349
Three-dimensional scatter plots with WebGL acceleration.
350

351
```javascript { .api }
352
interface Scatter3DTrace {
353
  type: 'scatter3d';
354
  x?: number[];
355
  y?: number[];
356
  z?: number[];
357
  mode?: 'markers' | 'lines' | 'text' | 'lines+markers' | 'lines+text' | 'markers+text' | 'lines+markers+text';
358
  marker?: {
359
    size?: number | number[];
360
    color?: string | string[] | number[];
361
    colorscale?: string | Array<[number, string]>;
362
    opacity?: number; // Must be scalar for WebGL
363
    symbol?: string;
364
    line?: {
365
      color?: string;
366
      width?: number;
367
    };
368
  };
369
  line?: {
370
    color?: string;
371
    width?: number;
372
  };
373
  text?: string | string[];
374
  projection?: {
375
    x?: { show?: boolean; opacity?: number; scale?: number; };
376
    y?: { show?: boolean; opacity?: number; scale?: number; };
377
    z?: { show?: boolean; opacity?: number; scale?: number; };
378
  };
379
}
380
```
381

382
### Surface Plots
383

384
3D surface visualization for mathematical functions or measured data.
385

386
```javascript { .api }
387
interface SurfaceTrace {
388
  type: 'surface';
389
  z: number[][];
390
  x?: number[];
391
  y?: number[];
392
  colorscale?: string | Array<[number, string]>;
393
  showscale?: boolean;
394
  opacity?: number;
395
  surfacecolor?: number[][];
396
  contours?: {
397
    x?: { show?: boolean; start?: number; end?: number; size?: number; color?: string; };
398
    y?: { show?: boolean; start?: number; end?: number; size?: number; color?: string; };
399
    z?: { show?: boolean; start?: number; end?: number; size?: number; color?: string; };
400
  };
401
  lighting?: {
402
    ambient?: number;
403
    diffuse?: number;
404
    specular?: number;
405
    roughness?: number;
406
    fresnel?: number;
407
  };
408
}
409
```
410

411
## Financial Charts
412

413
### Candlestick Charts
414

415
OHLC financial data visualization with candlestick representation.
416

417
```javascript { .api }
418
interface CandlestickTrace {
419
  type: 'candlestick';
420
  x?: Date[] | string[];
421
  open?: number[];
422
  high?: number[];
423
  low?: number[];
424
  close?: number[];
425
  increasing?: {
426
    line?: { color?: string; width?: number; };
427
    fillcolor?: string;
428
  };
429
  decreasing?: {
430
    line?: { color?: string; width?: number; };
431
    fillcolor?: string;
432
  };
433
  line?: {
434
    width?: number;
435
  };
436
  whiskerwidth?: number;
437
}
438
```
439

440
### OHLC Charts
441

442
Open-High-Low-Close financial charts with traditional bar representation.
443

444
```javascript { .api }
445
interface OHLCTrace {
446
  type: 'ohlc';
447
  x?: Date[] | string[];
448
  open?: number[];
449
  high?: number[];
450
  low?: number[];
451
  close?: number[];
452
  increasing?: {
453
    line?: { color?: string; width?: number; };
454
  };
455
  decreasing?: {
456
    line?: { color?: string; width?: number; };
457
  };
458
  line?: {
459
    width?: number;
460
  };
461
  tickwidth?: number;
462
}
463
```
464

465
### Waterfall Charts
466

467
Cumulative effect visualization showing how initial value is affected by intermediate positive/negative changes.
468

469
```javascript { .api }
470
interface WaterfallTrace {
471
  type: 'waterfall';
472
  x?: string[];
473
  y?: number[];
474
  base?: number;
475
  measure?: ('relative' | 'absolute' | 'total')[];
476
  text?: string | string[];
477
  textposition?: 'inside' | 'outside' | 'auto' | 'none';
478
  orientation?: 'v' | 'h';
479
  increasing?: {
480
    marker?: { color?: string; line?: { color?: string; width?: number; }; };
481
  };
482
  decreasing?: {
483
    marker?: { color?: string; line?: { color?: string; width?: number; }; };
484
  };
485
  totals?: {
486
    marker?: { color?: string; line?: { color?: string; width?: number; }; };
487
  };
488
}
489
```
490

491
## Geographic Charts
492

493
### Choropleth Maps
494

495
Geographic regions colored according to data values.
496

497
```javascript { .api }
498
interface ChoroplethTrace {
499
  type: 'choropleth';
500
  locations?: string[];
501
  z?: number[];
502
  locationmode?: 'ISO-3' | 'USA-states' | 'country names' | 'geojson-id';
503
  geojson?: object;
504
  featureidkey?: string;
505
  colorscale?: string | Array<[number, string]>;
506
  showscale?: boolean;
507
  colorbar?: ColorbarConfig;
508
  marker?: {
509
    line?: {
510
      color?: string;
511
      width?: number;
512
    };
513
  };
514
}
515
```
516

517
### Scatter Geo
518

519
Scatter plots on geographic maps.
520

521
```javascript { .api }
522
interface ScatterGeoTrace {
523
  type: 'scattergeo';
524
  lon?: number[];
525
  lat?: number[];
526
  locations?: string[];
527
  locationmode?: 'ISO-3' | 'USA-states' | 'country names';
528
  mode?: 'markers' | 'lines' | 'text' | 'lines+markers' | 'lines+text' | 'markers+text' | 'lines+markers+text';
529
  marker?: {
530
    size?: number | number[];
531
    color?: string | string[] | number[];
532
    symbol?: string;
533
    opacity?: number | number[];
534
    line?: {
535
      color?: string | string[];
536
      width?: number | number[];
537
    };
538
  };
539
  line?: {
540
    color?: string;
541
    width?: number;
542
    dash?: string;
543
  };
544
  text?: string | string[];
545
}
546
```
547

548
## Specialized Charts
549

550
### Sankey Diagrams
551

552
Flow diagrams showing directed flows between nodes.
553

554
```javascript { .api }
555
interface SankeyTrace {
556
  type: 'sankey';
557
  node?: {
558
    label?: string[];
559
    color?: string | string[];
560
    line?: {
561
      color?: string | string[];
562
      width?: number | number[];
563
    };
564
    pad?: number;
565
    thickness?: number;
566
    x?: number[];
567
    y?: number[];
568
  };
569
  link?: {
570
    source?: number[];
571
    target?: number[];
572
    value?: number[];
573
    color?: string | string[];
574
    line?: {
575
      color?: string | string[];
576
      width?: number | number[];
577
    };
578
  };
579
  orientation?: 'v' | 'h';
580
  arrangement?: 'snap' | 'perpendicular' | 'freeform' | 'fixed';
581
}
582
```
583

584
### Treemap Charts
585

586
Hierarchical data visualization using nested rectangles.
587

588
```javascript { .api }
589
interface TreemapTrace {
590
  type: 'treemap';
591
  labels?: string[];
592
  parents?: string[];
593
  values?: number[];
594
  ids?: string[];
595
  text?: string | string[];
596
  textinfo?: 'label' | 'text' | 'value' | 'label+text' | 'label+value' | 'text+value' | 'label+text+value' | 'none';
597
  branchvalues?: 'total' | 'remainder';
598
  level?: string;
599
  maxdepth?: number;
600
  marker?: {
601
    colors?: string[];
602
    colorscale?: string | Array<[number, string]>;
603
    showscale?: boolean;
604
    line?: {
605
      color?: string | string[];
606
      width?: number | number[];
607
    };
608
  };
609
  pathbar?: {
610
    visible?: boolean;
611
    side?: 'top' | 'bottom';
612
    edgeshape?: string;
613
    thickness?: number;
614
    textfont?: FontConfig;
615
  };
616
}
617
```
618

619
### Sunburst Charts
620

621
Hierarchical data visualization using concentric circles.
622

623
```javascript { .api }
624
interface SunburstTrace {
625
  type: 'sunburst';
626
  labels?: string[];
627
  parents?: string[];
628
  values?: number[];
629
  ids?: string[];
630
  text?: string | string[];
631
  textinfo?: 'label' | 'text' | 'value' | 'label+text' | 'label+value' | 'text+value' | 'label+text+value' | 'none';
632
  branchvalues?: 'total' | 'remainder';
633
  level?: string;
634
  maxdepth?: number;
635
  rotation?: number;
636
  sort?: boolean;
637
  marker?: {
638
    colors?: string[];
639
    colorscale?: string | Array<[number, string]>;
640
    showscale?: boolean;
641
    line?: {
642
      color?: string | string[];
643
      width?: number | number[];
644
    };
645
  };
646
}
647
```
648

649
## Usage Examples by Category
650

651
### Creating Multi-Trace Plots
652

653
```javascript
654
// Combining different chart types
655
const data = [
656
  {
657
    x: [1, 2, 3, 4, 5],
658
    y: [2, 4, 3, 5, 6],
659
    type: 'scatter',
660
    mode: 'lines',
661
    name: 'Line'
662
  },
663
  {
664
    x: [1, 2, 3, 4, 5],
665
    y: [1, 3, 2, 4, 5],
666
    type: 'bar',
667
    name: 'Bars',
668
    yaxis: 'y2'
669
  }
670
];
671

672
const layout = {
673
  yaxis: { title: 'Line Values' },
674
  yaxis2: { 
675
    title: 'Bar Values', 
676
    overlaying: 'y', 
677
    side: 'right' 
678
  }
679
};
680

681
await Plotly.newPlot('mixed-chart', data, layout);
682
```
683

684
### Chart Type Selection Guide
685

686
- **Scatter/Line**: Continuous data, trends, correlations
687
- **Bar**: Categorical comparisons, rankings
688
- **Pie**: Parts of a whole, proportions
689
- **Box/Violin**: Statistical distributions, outliers
690
- **Histogram**: Data frequency distributions
691
- **Heatmap**: 2D intensity data, correlation matrices
692
- **Contour**: Topographical data, mathematical functions
693
- **3D Surface**: 3D mathematical functions, terrain
694
- **Candlestick/OHLC**: Financial time series
695
- **Choropleth**: Regional geographic data
696
- **Sankey**: Flow processes, network diagrams
697
- **Treemap/Sunburst**: Hierarchical part-to-whole data
698

699
## Performance Considerations
700

701
- Use WebGL traces (`scattergl`, `scatter3d`) for large datasets (>1000 points)
702
- Heatmaps and contours can be memory-intensive with large Z matrices
703
- 3D traces require WebGL support
704
- Geographic traces may need additional topojson data files
705
- Consider data sampling or aggregation for very large datasets