0
# Plotly.js
1

2
Plotly.js is a comprehensive JavaScript data visualization library that enables developers to create interactive charts, graphs, and scientific visualizations directly in web browsers. It supports dozens of chart types including statistical charts, 3D graphs, scientific charts, SVG and tile maps, financial charts, and geographic visualizations.
3

4
## Package Information
5

6
- **Package Name**: plotly.js-dist
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install plotly.js-dist`
10

11
## Core Imports
12

13
```javascript
14
import Plotly from 'plotly.js-dist';
15
```
16

17
For specific bundles:
18

19
```javascript
20
import Plotly from 'plotly.js-dist/lib/core';
21
import Plotly from 'plotly.js-dist/lib/index-basic';
22
import Plotly from 'plotly.js-dist/lib/index-cartesian';
23
```
24

25
For CommonJS:
26

27
```javascript
28
const Plotly = require('plotly.js-dist');
29
```
30

31
## Basic Usage
32

33
```javascript
34
import Plotly from 'plotly.js-dist';
35

36
// Create a basic scatter plot
37
const trace = {
38
  x: [1, 2, 3, 4],
39
  y: [10, 11, 12, 13],
40
  type: 'scatter'
41
};
42

43
const data = [trace];
44
const layout = {
45
  title: 'My Plot'
46
};
47

48
// Create the plot
49
Plotly.newPlot('myDiv', data, layout);
50

51
// Update data
52
Plotly.restyle('myDiv', {'y': [[15, 16, 17, 18]]}, [0]);
53

54
// Update layout
55
Plotly.relayout('myDiv', {'title': 'Updated Plot'});
56
```
57

58
## Architecture
59

60
Plotly.js is built around several key components:
61

62
- **Modular System**: Registry-based loading of trace types, components, and transforms via `Plotly.register()`
63
- **Trace System**: 48+ chart types each with their own rendering, interaction, and styling capabilities
64
- **Layout System**: Comprehensive layout controls for axes, titles, legends, annotations, and visual styling
65
- **Component System**: Reusable UI components like legends, colorbars, toolbars, and interactive controls
66
- **Animation System**: Frame-based animations with smooth transitions between states
67
- **Bundle System**: Multiple distribution formats from basic (1MB) to full (4.6MB) for different use cases
68

69
## Capabilities
70

71
### Core Plotting Functions
72

73
Primary functions for creating and manipulating plots. These are the main entry points for all plotting operations.
74

75
```javascript { .api }
76
// Create a new plot from scratch
77
function newPlot(graphDiv, data, layout, config): Promise<HTMLElement>;
78

79
// Smart update with automatic diffing
80
function react(graphDiv, data, layout, config): Promise<HTMLElement>;
81

82
// Force complete redraw
83
function redraw(graphDiv): Promise<HTMLElement>;
84
```
85

86
[Core Plotting](./core-plotting.md)
87

88
### Data Updates
89

90
Functions for updating trace data and layout properties of existing plots without recreating them.
91

92
```javascript { .api }
93
// Update trace properties
94
function restyle(graphDiv, update, traces): Promise<HTMLElement>;
95

96
// Update layout properties  
97
function relayout(graphDiv, update): Promise<HTMLElement>;
98

99
// Combined trace and layout update
100
function update(graphDiv, traceUpdate, layoutUpdate, traces): Promise<HTMLElement>;
101
```
102

103
[Data Updates](./data-updates.md)
104

105
### Trace Management
106

107
Functions for adding, removing, and reordering traces in existing plots.
108

109
```javascript { .api }
110
// Add new traces
111
function addTraces(graphDiv, traces, newIndices): Promise<HTMLElement>;
112

113
// Remove traces
114
function deleteTraces(graphDiv, indices): Promise<HTMLElement>;
115

116
// Reorder traces
117
function moveTraces(graphDiv, currentIndices, newIndices): Promise<HTMLElement>;
118
```
119

120
[Trace Management](./trace-management.md)
121

122
### Data Streaming
123

124
Functions for efficiently appending or prepending data to existing traces, ideal for real-time data visualization.
125

126
```javascript { .api }
127
// Append data to traces
128
function extendTraces(graphDiv, update, indices, maxPoints): Promise<HTMLElement>;
129

130
// Prepend data to traces
131
function prependTraces(graphDiv, update, indices, maxPoints): Promise<HTMLElement>;
132
```
133

134
[Data Streaming](./data-streaming.md)
135

136
### Animation
137

138
Functions for creating smooth animated transitions between plot states and managing animation frames.
139

140
```javascript { .api }
141
// Animate between states
142
function animate(graphDiv, frames, animationOpts): Promise<void>;
143

144
// Add animation frames
145
function addFrames(graphDiv, frameList, indices): Promise<HTMLElement>;
146

147
// Remove animation frames
148
function deleteFrames(graphDiv, frameList): Promise<HTMLElement>;
149
```
150

151
[Animation](./animation.md)
152

153
### Chart Types
154

155
48+ trace types covering statistical, scientific, financial, geographic, and 3D visualizations.
156

157
```javascript { .api }
158
// Basic trace types
159
interface ScatterTrace {
160
  type: 'scatter';
161
  x?: number[];
162
  y?: number[];
163
  mode?: 'lines' | 'markers' | 'text' | 'lines+markers' | 'lines+text' | 'markers+text' | 'lines+markers+text' | 'none';
164
}
165

166
interface BarTrace {
167
  type: 'bar';
168
  x?: string[] | number[];
169
  y?: number[];
170
  orientation?: 'v' | 'h';
171
}
172

173
interface PieTrace {
174
  type: 'pie';
175
  labels?: string[];
176
  values?: number[];
177
}
178
```
179

180
[Chart Types](./chart-types.md)
181

182
### Layout System
183

184
Comprehensive layout controls for plot appearance, axes, legends, annotations, and interactive elements.
185

186
```javascript { .api }
187
interface Layout {
188
  title?: string | TitleConfig;
189
  xaxis?: AxisConfig;
190
  yaxis?: AxisConfig;
191
  legend?: LegendConfig;
192
  annotations?: AnnotationConfig[];
193
  shapes?: ShapeConfig[];
194
  images?: ImageConfig[];
195
  width?: number;
196
  height?: number;
197
  margin?: MarginConfig;
198
}
199
```
200

201
[Layout System](./layout-system.md)
202

203
### Export and Utilities
204

205
Functions for exporting plots as images, validating data, and managing plot lifecycle.
206

207
```javascript { .api }
208
// Export plot as image
209
function toImage(figure, options): Promise<string>;
210

211
// Download plot as image file
212
function downloadImage(graphDiv, options): Promise<void>;
213

214
// Validate plot data and layout
215
function validate(data, layout): ValidationError[];
216

217
// Clean up plot resources
218
function purge(graphDiv): HTMLElement;
219
```
220

221
[Export and Utilities](./export-utilities.md)
222

223
### Interactive Components
224

225
Built-in UI components for legends, colorbars, toolbars, and interactive controls.
226

227
```javascript { .api }
228
interface LegendConfig {
229
  bgcolor?: string;
230
  bordercolor?: string;
231
  borderwidth?: number;
232
  font?: FontConfig;
233
  orientation?: 'v' | 'h';
234
  x?: number;
235
  y?: number;
236
}
237

238
interface ColorbarConfig {
239
  title?: string;
240
  titleside?: 'right' | 'top' | 'bottom';
241
  thickness?: number;
242
  len?: number;
243
}
244
```
245

246
[Interactive Components](./interactive-components.md)
247

248
## Bundle Selection
249

250
Choose the appropriate bundle for your use case:
251

252
- **plotly.js** (4.6MB): Full functionality with all trace types
253
- **plotly-basic.js** (1MB): Basic charts (scatter, bar, pie)
254
- **plotly-cartesian.js** (1.3MB): 2D scientific/statistical charts
255
- **plotly-finance.js** (1.1MB): Financial charts (candlestick, OHLC, waterfall)
256
- **plotly-geo.js** (1.2MB): Geographic visualizations
257
- **plotly-gl2d.js** (1.5MB): High-performance 2D charts with WebGL
258
- **plotly-gl3d.js** (1.6MB): 3D visualizations
259
- **plotly-mapbox.js** (1.8MB): Mapbox integration (deprecated)
260

261
## Configuration
262

263
```javascript { .api }
264
interface Config {
265
  displayModeBar?: boolean | 'hover';
266
  modeBarButtons?: string[][];
267
  displaylogo?: boolean;
268
  responsive?: boolean;
269
  editable?: boolean;
270
  scrollZoom?: boolean;
271
  doubleClick?: 'reset' | 'autosize' | 'reset+autosize' | false;
272
  locale?: string;
273
}
274
```
275

276
## Types
277

278
```javascript { .api }
279
// Core data structure for plots
280
type PlotData = Array<Partial<ScatterTrace | BarTrace | PieTrace | HeatmapTrace | /* ... all other trace types */>>;
281

282
// Event data structures
283
interface PlotlyEvent {
284
  points: PlotlyEventPoint[];
285
  event: MouseEvent;
286
}
287

288
interface PlotlyEventPoint {
289
  data: any;
290
  fullData: any;
291
  curveNumber: number;
292
  pointNumber: number;
293
  x: any;
294
  y: any;
295
}
296

297
// Error types
298
interface ValidationError {
299
  code: string;
300
  message: string;
301
  path: string;
302
  value: any;
303
}
304
```