0
# Core Plotting Methods
1

2
Essential methods for creating, updating, and managing plots. These form the foundation of all plotly.js operations.
3

4
## Capabilities
5

6
### Create New Plot
7

8
Creates a new interactive plot from scratch.
9

10
```javascript { .api }
11
/**
12
 * Creates a new plot in the specified DOM element
13
 * @param gd - DOM element or element ID where plot will be rendered
14
 * @param data - Array of trace objects defining the data and chart types
15
 * @param layout - Layout object defining plot appearance and behavior
16
 * @param config - Configuration object for plot-level settings
17
 * @returns Promise that resolves when plot is created
18
 */
19
function newPlot(gd, data, layout, config);
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
// Basic scatter plot
26
Plotly.newPlot('myDiv', [{
27
    x: [1, 2, 3, 4],
28
    y: [10, 11, 12, 13],
29
    type: 'scatter'
30
}]);
31

32
// Multiple traces with layout
33
Plotly.newPlot('myDiv', [
34
    {
35
        x: [1, 2, 3, 4],
36
        y: [10, 11, 12, 13],
37
        type: 'scatter',
38
        name: 'Series 1'
39
    },
40
    {
41
        x: [1, 2, 3, 4],
42
        y: [16, 18, 17, 19],
43
        type: 'bar',
44
        name: 'Series 2'
45
    }
46
], {
47
    title: 'Combined Chart',
48
    xaxis: { title: 'X Axis' },
49
    yaxis: { title: 'Y Axis' }
50
}, {
51
    responsive: true,
52
    displayModeBar: true
53
});
54
```
55

56
### React (Efficient Update)
57

58
Efficiently updates a plot by comparing new data with existing data and only updating what has changed.
59

60
```javascript { .api }
61
/**
62
 * Updates plot efficiently by comparing new vs existing data
63
 * @param gd - DOM element containing the plot
64
 * @param data - New array of trace objects
65
 * @param layout - New layout object
66
 * @param config - New configuration object
67
 * @returns Promise that resolves when update is complete
68
 */
69
function react(gd, data, layout, config);
70
```
71

72
**Usage Examples:**
73

74
```javascript
75
// Initial plot
76
await Plotly.newPlot('myDiv', [{
77
    x: [1, 2, 3],
78
    y: [1, 4, 9],
79
    type: 'scatter'
80
}]);
81

82
// Efficient update - only changes what's different
83
await Plotly.react('myDiv', [{
84
    x: [1, 2, 3, 4],  // Added new point
85
    y: [1, 4, 9, 16], // Added new point
86
    type: 'scatter'
87
}]);
88
```
89

90
### Restyle Traces
91

92
Updates trace properties like data, colors, and styling without affecting layout.
93

94
```javascript { .api }
95
/**
96
 * Updates trace properties
97
 * @param gd - DOM element containing the plot
98
 * @param astr - Property path as string or object with property updates
99
 * @param val - New value(s) for the property
100
 * @param traces - Trace indices to update (optional, defaults to all traces)
101
 * @returns Promise that resolves when restyle is complete
102
 */
103
function restyle(gd, astr, val, traces);
104
```
105

106
**Usage Examples:**
107

108
```javascript
109
// Update y-data for all traces
110
Plotly.restyle('myDiv', 'y', [[5, 10, 15, 20]]);
111

112
// Update multiple properties
113
Plotly.restyle('myDiv', {
114
    'marker.color': 'red',
115
    'marker.size': 10
116
});
117

118
// Update specific traces only
119
Plotly.restyle('myDiv', 'marker.color', 'blue', [0, 2]); // Only traces 0 and 2
120

121
// Update different values for different traces
122
Plotly.restyle('myDiv', 'marker.color', ['red', 'blue', 'green']);
123
```
124

125
### Relayout
126

127
Updates layout properties like axes, title, and plot dimensions.
128

129
```javascript { .api }
130
/**
131
 * Updates layout properties
132
 * @param gd - DOM element containing the plot
133
 * @param astr - Property path as string or object with property updates
134
 * @param val - New value for the property (not needed if astr is object)
135
 * @returns Promise that resolves when relayout is complete
136
 */
137
function relayout(gd, astr, val);
138
```
139

140
**Usage Examples:**
141

142
```javascript
143
// Update title
144
Plotly.relayout('myDiv', 'title', 'New Plot Title');
145

146
// Update axis ranges
147
Plotly.relayout('myDiv', {
148
    'xaxis.range': [0, 10],
149
    'yaxis.range': [0, 20]
150
});
151

152
// Update plot dimensions
153
Plotly.relayout('myDiv', {
154
    width: 800,
155
    height: 600
156
});
157
```
158

159
### Update (Combined Restyle and Relayout)
160

161
Updates both trace and layout properties in a single operation.
162

163
```javascript { .api }
164
/**
165
 * Updates both trace and layout properties
166
 * @param gd - DOM element containing the plot
167
 * @param traceUpdate - Object with trace property updates
168
 * @param layoutUpdate - Object with layout property updates
169
 * @param traces - Trace indices to update (optional)
170
 * @returns Promise that resolves when update is complete
171
 */
172
function update(gd, traceUpdate, layoutUpdate, traces);
173
```
174

175
**Usage Examples:**
176

177
```javascript
178
// Update traces and layout together
179
Plotly.update('myDiv', 
180
    { 'marker.color': 'red' },      // Trace updates
181
    { 'title': 'Updated Chart' }    // Layout updates
182
);
183

184
// Update specific traces with layout changes
185
Plotly.update('myDiv',
186
    { 'y': [[1, 2, 3, 4]] },
187
    { 'yaxis.title': 'New Y Label' },
188
    [0]  // Only update trace 0
189
);
190
```
191

192
### Redraw
193

194
Forces a complete redraw of the plot. Useful when manual DOM changes have been made.
195

196
```javascript { .api }
197
/**
198
 * Forces a complete redraw of the plot
199
 * @param gd - DOM element containing the plot
200
 * @returns Promise that resolves when redraw is complete
201
 */
202
function redraw(gd);
203
```
204

205
**Usage Examples:**
206

207
```javascript
208
// Force complete redraw
209
await Plotly.redraw('myDiv');
210

211
// Often used after manual DOM manipulation
212
document.getElementById('myDiv').style.width = '800px';
213
await Plotly.redraw('myDiv');
214
```
215

216
### Purge
217

218
Completely removes the plot and cleans up all associated data, event listeners, and DOM elements.
219

220
```javascript { .api }
221
/**
222
 * Removes plot and cleans up all associated data
223
 * @param gd - DOM element containing the plot
224
 * @returns The gd element that was purged
225
 */
226
function purge(gd);
227
```
228

229
**Usage Examples:**
230

231
```javascript
232
// Clean up plot before removing from DOM
233
Plotly.purge('myDiv');
234
document.getElementById('myDiv').remove();
235

236
// Clean up before creating new plot
237
Plotly.purge('myDiv');
238
Plotly.newPlot('myDiv', newData, newLayout);
239
```
240

241
### Trace Management
242

243
Methods for dynamically adding, removing, and reordering traces.
244

245
```javascript { .api }
246
/**
247
 * Adds new traces to existing plot
248
 * @param gd - DOM element containing the plot
249
 * @param traces - Single trace object or array of trace objects to add
250
 * @param newIndices - Positions where traces should be inserted
251
 * @returns Promise that resolves when traces are added
252
 */
253
function addTraces(gd, traces, newIndices);
254

255
/**
256
 * Removes traces from plot
257
 * @param gd - DOM element containing the plot
258
 * @param indices - Index or array of indices of traces to remove
259
 * @returns Promise that resolves when traces are removed
260
 */
261
function deleteTraces(gd, indices);
262

263
/**
264
 * Reorders traces in the plot
265
 * @param gd - DOM element containing the plot
266
 * @param currentIndices - Current indices of traces to move
267
 * @param newIndices - New positions for the traces
268
 * @returns Promise that resolves when traces are moved
269
 */
270
function moveTraces(gd, currentIndices, newIndices);
271
```
272

273
**Usage Examples:**
274

275
```javascript
276
// Add a new trace
277
await Plotly.addTraces('myDiv', {
278
    x: [1, 2, 3],
279
    y: [2, 4, 6],
280
    type: 'scatter',
281
    name: 'New Series'
282
});
283

284
// Add multiple traces at specific positions
285
await Plotly.addTraces('myDiv', [
286
    { x: [1, 2], y: [1, 4], type: 'scatter' },
287
    { x: [1, 2], y: [2, 8], type: 'bar' }
288
], [1, 3]); // Insert at positions 1 and 3
289

290
// Remove traces
291
await Plotly.deleteTraces('myDiv', [0, 2]); // Remove traces 0 and 2
292

293
// Reorder traces
294
await Plotly.moveTraces('myDiv', [0, 1], [1, 0]); // Swap first two traces
295
```
296

297
### Shape Management
298

299
Methods for managing interactive shapes on plots.
300

301
```javascript { .api }
302
/**
303
 * Delete currently active shape
304
 * @param gd - DOM element containing the plot
305
 * @returns Updated plot element
306
 */
307
function deleteActiveShape(gd: any): any;
308
```
309

310
**Usage Examples:**
311

312
```javascript
313
// Delete active shape when user presses delete key
314
document.addEventListener('keydown', function(event) {
315
    if (event.key === 'Delete' || event.key === 'Backspace') {
316
        Plotly.deleteActiveShape('myDiv');
317
    }
318
});
319

320
// Delete active shape with custom button
321
function deleteCurrentShape() {
322
    Plotly.deleteActiveShape('myDiv');
323
}
324

325
// Use in editable mode with shape drawing
326
Plotly.newPlot('myDiv', data, layout, {
327
    editable: true,
328
    modeBarButtonsToAdd: [{
329
        name: 'Delete Shape',
330
        icon: Plotly.Icons.eraseshape,
331
        click: function(gd) {
332
            Plotly.deleteActiveShape(gd);
333
        }
334
    }]
335
});
336
```
337

338
### Global Configuration
339

340
Set global configuration options that affect all plots.
341

342
```javascript { .api }
343
/**
344
 * Set global plot configuration
345
 * @param config - Global configuration object
346
 */
347
function setPlotConfig(config: GlobalConfig): void;
348

349
interface GlobalConfig {
350
  plotlyServerURL?: string;
351
  showSendToCloud?: boolean;
352
  showEditInChartStudio?: boolean;
353
  linkText?: string;
354
  showTips?: boolean;
355
  locale?: string;
356
  locales?: { [locale: string]: any };
357
  toImageButtonOptions?: {
358
    format?: 'png' | 'svg' | 'jpeg' | 'webp';
359
    filename?: string;
360
    height?: number;
361
    width?: number;
362
    scale?: number;
363
  };
364
}
365
```
366

367
**Usage Examples:**
368

369
```javascript
370
// Set global defaults
371
Plotly.setPlotConfig({
372
    showSendToCloud: false,
373
    showEditInChartStudio: false,
374
    locale: 'en-US',
375
    toImageButtonOptions: {
376
        format: 'png',
377
        filename: 'plot',
378
        scale: 2
379
    }
380
});
381

382
// Configure for offline use
383
Plotly.setPlotConfig({
384
    showSendToCloud: false,
385
    showEditInChartStudio: false,
386
    plotlyServerURL: false
387
});
388

389
// Set default export options
390
Plotly.setPlotConfig({
391
    toImageButtonOptions: {
392
        format: 'svg',
393
        width: 1200,
394
        height: 800,
395
        scale: 1
396
    }
397
});
398
```
399

400
### Extend and Prepend Data
401

402
Methods for efficiently adding data points to existing traces.
403

404
```javascript { .api }
405
/**
406
 * Appends new data points to existing traces
407
 * @param gd - DOM element containing the plot
408
 * @param update - Object with arrays of new data points
409
 * @param indices - Trace indices to update
410
 * @param maxPoints - Maximum number of points to keep per trace
411
 * @returns Promise that resolves when data is extended
412
 */
413
function extendTraces(gd, update, indices, maxPoints);
414

415
/**
416
 * Prepends new data points to existing traces
417
 * @param gd - DOM element containing the plot  
418
 * @param update - Object with arrays of new data points
419
 * @param indices - Trace indices to update
420
 * @param maxPoints - Maximum number of points to keep per trace
421
 * @returns Promise that resolves when data is prepended
422
 */
423
function prependTraces(gd, update, indices, maxPoints);
424
```
425

426
**Usage Examples:**
427

428
```javascript
429
// Add new points to the end of traces
430
await Plotly.extendTraces('myDiv', {
431
    x: [[5, 6]], // New x values for trace 0
432
    y: [[25, 36]] // New y values for trace 0
433
}, [0]);
434

435
// Add points with maximum limit (useful for streaming data)
436
await Plotly.extendTraces('myDiv', {
437
    x: [[new Date()]],
438
    y: [[Math.random()]]
439
}, [0], 100); // Keep only last 100 points
440

441
// Add points to beginning
442
await Plotly.prependTraces('myDiv', {
443
    x: [[-1, 0]],
444
    y: [[1, 0]]
445
}, [0]);
446
```
447

448
## Parameter Types
449

450
### Graph Division (gd)
451
```javascript { .api }
452
// Can be a DOM element or string ID
453
type GraphDiv = HTMLElement | string;
454
```
455

456
### Trace Object
457
```javascript { .api }
458
interface Trace {
459
  type: string;
460
  x?: any[];
461
  y?: any[];
462
  z?: any[];
463
  mode?: string;
464
  name?: string;
465
  visible?: boolean | 'legendonly';
466
  showlegend?: boolean;
467
  marker?: Partial<Marker>;
468
  line?: Partial<Line>;
469
  fill?: string;
470
  fillcolor?: string;
471
  text?: string | string[];
472
  hovertext?: string | string[];
473
  hovertemplate?: string;
474
  hoverinfo?: string;
475
}
476
```
477

478
### Layout Object
479
```javascript { .api }
480
interface Layout {
481
  title?: string | Partial<Title>;
482
  width?: number;
483
  height?: number;
484
  autosize?: boolean;
485
  margin?: Partial<Margin>;
486
  paper_bgcolor?: string;
487
  plot_bgcolor?: string;
488
  font?: Partial<Font>;
489
  xaxis?: Partial<Axis>;
490
  yaxis?: Partial<Axis>;
491
  legend?: Partial<Legend>;
492
  annotations?: Partial<Annotation>[];
493
  shapes?: Partial<Shape>[];
494
  images?: Partial<Image>[];
495
}
496
```
497

498
### Config Object
499
```javascript { .api }
500
interface Config {
501
  staticPlot?: boolean;
502
  editable?: boolean;
503
  displayModeBar?: boolean | 'hover';
504
  modeBarButtonsToRemove?: string[];
505
  responsive?: boolean;
506
  locale?: string;
507
  scrollZoom?: boolean;
508
  doubleClick?: 'reset' | 'autosize' | 'reset+autosize' | false;
509
}
510
```