0
# Core Plotting Functions
1

2
Primary functions for creating and manipulating plots. These are the main entry points for all plotting operations in Plotly.js.
3

4
## Capabilities
5

6
### newPlot
7

8
Creates a new plot from scratch, completely replacing any existing plot in the target element.
9

10
```javascript { .api }
11
/**
12
 * Creates a new plot from scratch
13
 * @param graphDiv - DOM element ID (string) or element reference
14
 * @param data - Array of trace objects defining the data and chart types
15
 * @param layout - Layout object controlling plot appearance (optional)
16
 * @param config - Configuration object for plot behavior (optional)
17
 * @returns Promise that resolves to the graph div element
18
 */
19
function newPlot(
20
  graphDiv: string | HTMLElement,
21
  data: PlotData,
22
  layout?: Partial<Layout>,
23
  config?: Partial<Config>
24
): Promise<HTMLElement>;
25
```
26

27
**Usage Examples:**
28

29
```javascript
30
import Plotly from 'plotly.js-dist';
31

32
// Basic line chart
33
const data = [{
34
  x: [1, 2, 3, 4],
35
  y: [10, 11, 12, 13],
36
  type: 'scatter',
37
  mode: 'lines+markers'
38
}];
39

40
const layout = {
41
  title: 'Sample Line Chart',
42
  xaxis: { title: 'X Axis' },
43
  yaxis: { title: 'Y Axis' }
44
};
45

46
await Plotly.newPlot('chart-div', data, layout);
47

48
// Multiple traces
49
const multiData = [
50
  {
51
    x: [1, 2, 3, 4],
52
    y: [10, 11, 12, 13],
53
    name: 'Series 1',
54
    type: 'scatter'
55
  },
56
  {
57
    x: [1, 2, 3, 4],
58
    y: [16, 15, 14, 13],
59
    name: 'Series 2',
60
    type: 'scatter'
61
  }
62
];
63

64
await Plotly.newPlot('multi-chart', multiData, { title: 'Multiple Series' });
65
```
66

67
### react
68

69
Smart plotting function that compares the new state against the existing state and performs only the necessary updates for optimal performance.
70

71
```javascript { .api }
72
/**
73
 * Smart update function with automatic diffing for optimal performance
74
 * @param graphDiv - DOM element ID (string) or element reference
75
 * @param data - Array of trace objects
76
 * @param layout - Layout object (optional)
77
 * @param config - Configuration object (optional)
78
 * @returns Promise that resolves to the graph div element
79
 */
80
function react(
81
  graphDiv: string | HTMLElement,
82
  data: PlotData,
83
  layout?: Partial<Layout>,
84
  config?: Partial<Config>
85
): Promise<HTMLElement>;
86
```
87

88
**Usage Examples:**
89

90
```javascript
91
// Initial plot
92
let currentData = [{
93
  x: [1, 2, 3],
94
  y: [4, 5, 6],
95
  type: 'scatter'
96
}];
97

98
await Plotly.newPlot('chart', currentData);
99

100
// Efficient update - only changes what's different
101
currentData[0].y = [7, 8, 9];
102
await Plotly.react('chart', currentData);
103

104
// Adding a new trace efficiently
105
currentData.push({
106
  x: [1, 2, 3],
107
  y: [1, 2, 3],
108
  type: 'bar'
109
});
110
await Plotly.react('chart', currentData);
111
```
112

113
### redraw
114

115
Forces a complete redraw of an existing plot. Use when the plot data hasn't changed but visual refresh is needed.
116

117
```javascript { .api }
118
/**
119
 * Forces a complete redraw of an existing plot
120
 * @param graphDiv - DOM element ID (string) or element reference
121
 * @returns Promise that resolves to the graph div element
122
 */
123
function redraw(graphDiv: string | HTMLElement): Promise<HTMLElement>;
124
```
125

126
**Usage Examples:**
127

128
```javascript
129
// After external DOM changes that might affect plot
130
await Plotly.redraw('my-chart');
131

132
// After window resize or container changes
133
window.addEventListener('resize', async () => {
134
  await Plotly.redraw('responsive-chart');
135
});
136
```
137

138
### purge
139

140
Completely removes a plot and cleans up all associated resources, event listeners, and memory allocations.
141

142
```javascript { .api }
143
/**
144
 * Completely removes a plot and cleans up all resources
145
 * @param graphDiv - DOM element ID (string) or element reference
146
 * @returns The graph div element
147
 */
148
function purge(graphDiv: string | HTMLElement): HTMLElement;
149
```
150

151
**Usage Examples:**
152

153
```javascript
154
// Clean up before removing from DOM
155
Plotly.purge('chart-to-remove');
156
document.getElementById('chart-to-remove').remove();
157

158
// Clean up in React componentWillUnmount
159
componentWillUnmount() {
160
  if (this.chartRef.current) {
161
    Plotly.purge(this.chartRef.current);
162
  }
163
}
164
```
165

166
## Event Handling
167

168
All core plotting functions emit events that can be listened to:
169

170
```javascript { .api }
171
// Plot creation/update events
172
interface PlotEvents {
173
  'plotly_afterplot': () => void;
174
  'plotly_beforeplot': () => void;
175
  'plotly_plotready': () => void;
176
}
177
```
178

179
**Usage Examples:**
180

181
```javascript
182
const chartDiv = document.getElementById('my-chart');
183

184
chartDiv.on('plotly_afterplot', () => {
185
  console.log('Plot rendering complete');
186
});
187

188
chartDiv.on('plotly_plotready', () => {
189
  console.log('Plot is ready for interaction');
190
});
191

192
await Plotly.newPlot('my-chart', data, layout);
193
```
194

195
## Error Handling
196

197
Core plotting functions can throw errors for invalid input:
198

199
```javascript
200
try {
201
  await Plotly.newPlot('chart', invalidData);
202
} catch (error) {
203
  console.error('Plot creation failed:', error.message);
204
}
205

206
// Validate data before plotting
207
const errors = Plotly.validate(data, layout);
208
if (errors.length > 0) {
209
  console.error('Validation errors:', errors);
210
} else {
211
  await Plotly.newPlot('chart', data, layout);
212
}
213
```
214

215
## Performance Considerations
216

217
- Use `react()` instead of `newPlot()` for updates when possible
218
- Use `redraw()` sparingly - it's expensive
219
- Call `purge()` when removing plots to prevent memory leaks
220
- Consider bundle size - use specific bundles (basic, cartesian, etc.) for smaller applications
221
- For large datasets (>1000 points), consider WebGL traces (`scattergl`)
222

223
## Types
224

225
```javascript { .api }
226
// Configuration options for core plotting
227
interface Config {
228
  displayModeBar?: boolean | 'hover';
229
  displaylogo?: boolean;
230
  responsive?: boolean;
231
  editable?: boolean;
232
  scrollZoom?: boolean;
233
  doubleClick?: 'reset' | 'autosize' | 'reset+autosize' | false;
234
  showTips?: boolean;
235
  locale?: string;
236
  modeBarButtons?: string[][];
237
}
238

239
// Basic plot data structure
240
type PlotData = Array<Partial<PlotlyTrace>>;
241

242
interface PlotlyTrace {
243
  type: string;
244
  name?: string;
245
  visible?: boolean | 'legendonly';
246
  showlegend?: boolean;
247
  opacity?: number;
248
  x?: any[];
249
  y?: any[];
250
  z?: any[];
251
  [key: string]: any;
252
}
253
```