0
# Plotly.js
1
2
Plotly.js is a comprehensive JavaScript data visualization library that enables creation of interactive statistical charts, 3D graphs, scientific visualizations, SVG and tile maps, financial charts, and more. The library serves as the foundation for Python and R plotting ecosystems (Plotly.py and Plotly.R) and provides a complete charting solution with dozens of chart types including bar charts, histograms, heatmaps, contour plots, 3D surfaces, scatter plots, and specialized visualizations like treemaps, sunburst charts, and scientific plots.
3
4
## Package Information
5
6
- **Package Name**: plotly.js
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install plotly.js-dist-min` (minified) or `npm install plotly.js-dist` (unminified)
10
11
## Core Imports
12
13
ES6 Module:
14
```javascript
15
import Plotly from 'plotly.js-dist-min';
16
```
17
18
CommonJS:
19
```javascript
20
var Plotly = require('plotly.js-dist-min');
21
```
22
23
Script tag (CDN):
24
```html
25
<script src="https://cdn.plot.ly/plotly-3.1.0.min.js" charset="utf-8"></script>
26
```
27
28
## Basic Usage
29
30
```javascript
31
// Create a simple line chart
32
Plotly.newPlot('myDiv', [{
33
x: [1, 2, 3, 4],
34
y: [10, 11, 12, 13],
35
type: 'scatter'
36
}], {
37
title: 'My First Plot',
38
width: 600,
39
height: 400
40
});
41
42
// Update the plot
43
Plotly.restyle('myDiv', 'y', [[16, 18, 20, 17]]);
44
45
// Add a new trace
46
Plotly.addTraces('myDiv', {
47
x: [1, 2, 3, 4],
48
y: [12, 9, 15, 12],
49
type: 'scatter',
50
mode: 'markers'
51
});
52
```
53
54
## Architecture
55
56
Plotly.js is built around several key components:
57
58
- **Core Plotting Engine**: The `newPlot`, `react`, and `redraw` methods provide the foundation for creating and updating plots
59
- **Trace System**: 58 different trace types covering everything from basic scatter plots to complex 3D visualizations
60
- **Layout System**: Comprehensive layout configuration including axes, legends, annotations, and interactive components
61
- **Update System**: Efficient methods for modifying existing plots (`restyle`, `relayout`, `update`)
62
- **Event System**: Complete event handling for user interactions, animations, and plot lifecycle events
63
- **Export System**: Built-in capabilities for exporting plots to various image formats and serialization
64
65
## Capabilities
66
67
### Core Plotting Methods
68
69
Essential methods for creating, updating, and managing plots. These form the foundation of all plotly.js operations.
70
71
```javascript { .api }
72
function newPlot(gd, data, layout, config);
73
function react(gd, data, layout, config);
74
function restyle(gd, astr, val, traces);
75
function relayout(gd, astr, val);
76
function redraw(gd);
77
function purge(gd);
78
function deleteActiveShape(gd);
79
function setPlotConfig(config);
80
```
81
82
[Core Plotting Methods](./core-plotting.md)
83
84
### Basic Chart Types
85
86
Common chart types for everyday data visualization including scatter plots, bar charts, histograms, pie charts, and box plots.
87
88
```javascript { .api }
89
// Scatter plot trace
90
{
91
x: number[],
92
y: number[],
93
type: 'scatter',
94
mode: 'markers' | 'lines' | 'markers+lines'
95
}
96
97
// Bar chart trace
98
{
99
x: string[],
100
y: number[],
101
type: 'bar'
102
}
103
```
104
105
[Basic Chart Types](./basic-charts.md)
106
107
### Statistical Charts
108
109
Advanced statistical visualizations including histograms, box plots, violin plots, and distribution analysis charts.
110
111
```javascript { .api }
112
// Histogram trace
113
{
114
x: number[],
115
type: 'histogram',
116
nbinsx: number
117
}
118
119
// Box plot trace
120
{
121
y: number[],
122
type: 'box',
123
name: string
124
}
125
```
126
127
[Statistical Charts](./statistical-charts.md)
128
129
### 3D Visualizations
130
131
Three-dimensional plotting capabilities including 3D scatter plots, surfaces, meshes, and volume rendering.
132
133
```javascript { .api }
134
// 3D scatter plot
135
{
136
x: number[],
137
y: number[],
138
z: number[],
139
type: 'scatter3d',
140
mode: 'markers'
141
}
142
143
// Surface plot
144
{
145
z: number[][],
146
type: 'surface'
147
}
148
```
149
150
[3D Visualizations](./3d-charts.md)
151
152
### Additional Chart Types
153
154
Plotly.js includes many additional specialized chart types for specific use cases:
155
156
- **Scientific Charts**: Contour plots, heatmaps, and mathematical visualizations
157
- **Geographic Maps**: Choropleth maps, scatter geo plots, and Mapbox integration
158
- **Financial Charts**: Candlestick charts, OHLC charts, and waterfall charts
159
- **Specialized Visualizations**: Treemaps, sunburst charts, sankey diagrams, and parallel coordinates
160
161
These advanced chart types follow similar patterns to the basic charts with specialized trace configurations and data requirements. Each trace type has its own specific attributes and options for customization.
162
163
### Layout Configuration
164
165
Comprehensive layout options for customizing plot appearance, axes, legends, annotations, and interactive components.
166
167
```javascript { .api }
168
interface Layout {
169
title?: string | Partial<Title>;
170
width?: number;
171
height?: number;
172
xaxis?: Partial<Axis>;
173
yaxis?: Partial<Axis>;
174
legend?: Partial<Legend>;
175
annotations?: Partial<Annotation>[];
176
shapes?: Partial<Shape>[];
177
}
178
```
179
180
[Layout Configuration](./layout.md)
181
182
### Animation and Frames
183
184
Animation capabilities for creating dynamic visualizations with smooth transitions between data states.
185
186
```javascript { .api }
187
function animate(gd, frameOrGroupNameOrFrameList, animationOpts);
188
function addFrames(gd, frameList, indices);
189
function deleteFrames(gd, frameList);
190
```
191
192
Animation methods are part of the core plotting API and are documented in the Core Plotting Methods section.
193
194
### Events and Interactions
195
196
Complete event system for handling user interactions, plot updates, and custom behaviors.
197
198
```javascript { .api }
199
// Event methods
200
gd.on(event, handler);
201
gd.once(event, handler);
202
gd.removeListener(event, handler);
203
204
// Common events
205
'plotly_click'
206
'plotly_hover'
207
'plotly_selected'
208
'plotly_restyle'
209
'plotly_relayout'
210
```
211
212
[Events and Interactions](./events.md)
213
214
### Export and Utilities
215
216
Export capabilities for generating images, validating data, and working with plot schemas and templates.
217
218
```javascript { .api }
219
function toImage(gd, opts);
220
function downloadImage(gd, opts);
221
function validate(data, layout);
222
function makeTemplate(gd);
223
function validateTemplate(template);
224
225
// PlotSchema methods
226
PlotSchema.get();
227
PlotSchema.crawl(attrs, callback, level, attrString);
228
PlotSchema.isValObject(obj);
229
PlotSchema.findArrayAttributes(trace);
230
231
// Plots utilities
232
Plots.resize(gd);
233
Plots.graphJson(gd, dataOnly, layout, data, frames);
234
Plots.sendDataToCloud(gd, options);
235
236
// Snapshot utilities
237
Snapshot.clone(gd, options);
238
Snapshot.toSVG(gd, format, scale);
239
Snapshot.svgToImg(svg, format, scale);
240
```
241
242
[Export and Utilities](./export-utilities.md)
243
244
## Configuration Options
245
246
Global configuration options control plot behavior, interactivity, mode bar, and integration with external services.
247
248
```javascript { .api }
249
interface Config {
250
staticPlot?: boolean;
251
editable?: boolean;
252
displayModeBar?: boolean | 'hover';
253
responsive?: boolean;
254
locale?: string;
255
}
256
```
257
258
## Common Data Structures
259
260
### Trace Data Structure
261
```javascript { .api }
262
interface Trace {
263
type: string;
264
x?: any[];
265
y?: any[];
266
z?: any[];
267
mode?: string;
268
name?: string;
269
marker?: Partial<Marker>;
270
line?: Partial<Line>;
271
text?: string | string[];
272
hovertemplate?: string;
273
}
274
```
275
276
### Layout Structure
277
```javascript { .api }
278
interface Layout {
279
title?: string | Partial<Title>;
280
width?: number;
281
height?: number;
282
margin?: Partial<Margin>;
283
font?: Partial<Font>;
284
paper_bgcolor?: string;
285
plot_bgcolor?: string;
286
}
287
```
288
289
### Configuration Structure
290
```javascript { .api }
291
interface Config {
292
displayModeBar?: boolean | 'hover';
293
modeBarButtonsToRemove?: string[];
294
staticPlot?: boolean;
295
responsive?: boolean;
296
editable?: boolean;
297
scrollZoom?: boolean;
298
doubleClick?: 'reset' | 'autosize' | 'reset+autosize' | false;
299
}
300
```