0
# Data Updates
1

2
Functions for updating trace data and layout properties of existing plots without recreating them. These functions provide efficient ways to modify plots while preserving performance and user interactions.
3

4
## Capabilities
5

6
### restyle
7

8
Updates trace properties of existing traces. Can modify styling, data, or any trace-level attributes.
9

10
```javascript { .api }
11
/**
12
 * Updates trace attributes of existing traces
13
 * @param graphDiv - DOM element ID (string) or element reference
14
 * @param update - Object with attribute paths as keys and new values, or attribute string with value
15
 * @param traces - Array of trace indices to update, or single index (optional, defaults to all traces)
16
 * @returns Promise that resolves to the graph div element
17
 */
18
function restyle(
19
  graphDiv: string | HTMLElement,
20
  update: {[attributePath: string]: any} | string,
21
  traces?: number | number[]
22
): Promise<HTMLElement>;
23

24
// Alternative signature for single attribute
25
function restyle(
26
  graphDiv: string | HTMLElement,
27
  attributePath: string,
28
  value: any,
29
  traces?: number | number[]
30
): Promise<HTMLElement>;
31
```
32

33
**Usage Examples:**
34

35
```javascript
36
import Plotly from 'plotly.js-dist';
37

38
// Update y data for first trace
39
await Plotly.restyle('chart', {'y': [[5, 6, 7, 8]]}, [0]);
40

41
// Update marker color for all traces
42
await Plotly.restyle('chart', {'marker.color': 'red'});
43

44
// Update multiple attributes at once
45
await Plotly.restyle('chart', {
46
  'marker.color': 'blue',
47
  'marker.size': 10,
48
  'line.width': 3
49
}, [0]);
50

51
// Update specific trace by index
52
await Plotly.restyle('chart', {'name': 'Updated Series'}, [1]);
53

54
// Single attribute syntax
55
await Plotly.restyle('chart', 'marker.color', 'green', [0]);
56

57
// Update data arrays with different values per trace
58
await Plotly.restyle('chart', {
59
  'y': [[1, 2, 3], [4, 5, 6]]  // First array for trace 0, second for trace 1
60
}, [0, 1]);
61
```
62

63
### relayout
64

65
Updates layout properties of the plot. Can modify axes, titles, styling, and any layout-level configuration.
66

67
```javascript { .api }
68
/**
69
 * Updates layout attributes of an existing plot
70
 * @param graphDiv - DOM element ID (string) or element reference  
71
 * @param update - Object with layout attribute paths as keys and new values
72
 * @returns Promise that resolves to the graph div element
73
 */
74
function relayout(
75
  graphDiv: string | HTMLElement,
76
  update: {[attributePath: string]: any}
77
): Promise<HTMLElement>;
78
```
79

80
**Usage Examples:**
81

82
```javascript
83
// Update plot title
84
await Plotly.relayout('chart', {'title': 'New Chart Title'});
85

86
// Update axis properties
87
await Plotly.relayout('chart', {
88
  'xaxis.title': 'Time (seconds)',
89
  'yaxis.title': 'Value',
90
  'xaxis.range': [0, 10],
91
  'yaxis.range': [0, 100]
92
});
93

94
// Update plot dimensions
95
await Plotly.relayout('chart', {
96
  'width': 800,
97
  'height': 600
98
});
99

100
// Update multiple layout properties
101
await Plotly.relayout('chart', {
102
  'title': 'Updated Chart',
103
  'plot_bgcolor': 'lightgray',
104
  'paper_bgcolor': 'white',
105
  'font.size': 14,
106
  'showlegend': false
107
});
108

109
// Update axis range (useful for zooming programmatically)
110
await Plotly.relayout('chart', {
111
  'xaxis.range': [new Date('2023-01-01'), new Date('2023-12-31')]
112
});
113
```
114

115
### update  
116

117
Combines restyle and relayout operations in a single function call for efficiency. Ideal when updating both trace and layout properties simultaneously.
118

119
```javascript { .api }
120
/**
121
 * Combined restyle and relayout in a single call
122
 * @param graphDiv - DOM element ID (string) or element reference
123
 * @param traceUpdate - Object with trace attribute updates (same format as restyle)
124
 * @param layoutUpdate - Object with layout attribute updates (same format as relayout)
125
 * @param traces - Array of trace indices for trace updates (optional, defaults to all)
126
 * @returns Promise that resolves to the graph div element
127
 */
128
function update(
129
  graphDiv: string | HTMLElement,
130
  traceUpdate: {[attributePath: string]: any},
131
  layoutUpdate: {[attributePath: string]: any},
132
  traces?: number | number[]
133
): Promise<HTMLElement>;
134
```
135

136
**Usage Examples:**
137

138
```javascript
139
// Update both trace data and layout title
140
await Plotly.update('chart', 
141
  {'y': [[10, 20, 30]]},  // Trace update
142
  {'title': 'Updated Data and Title'}  // Layout update
143
);
144

145
// Update styling and layout together
146
await Plotly.update('chart',
147
  {
148
    'marker.color': 'red',
149
    'marker.size': 12
150
  },
151
  {
152
    'plot_bgcolor': 'lightblue',
153
    'xaxis.gridcolor': 'white'
154
  },
155
  [0, 1]  // Apply trace updates to first two traces
156
);
157

158
// Complex update with multiple changes
159
await Plotly.update('chart',
160
  {
161
    'x': [[1, 2, 3, 4, 5]],
162
    'y': [[5, 10, 15, 20, 25]],
163
    'mode': 'lines+markers',
164
    'name': 'Updated Series'
165
  },
166
  {
167
    'title': 'Real-time Data',
168
    'xaxis.title': 'Time',
169
    'yaxis.title': 'Measurement',
170
    'width': 900
171
  }
172
);
173
```
174

175
## Attribute Path Syntax
176

177
All update functions use dot notation to specify nested attributes:
178

179
```javascript
180
// Examples of attribute paths
181
'marker.color'              // Marker color
182
'marker.line.width'         // Marker outline width  
183
'line.color'               // Line color
184
'xaxis.range'              // X-axis range
185
'xaxis.title.text'         // X-axis title text
186
'legend.bgcolor'           // Legend background color
187
'annotations[0].text'      // First annotation text
188
'shapes[1].fillcolor'      // Second shape fill color
189
```
190

191
## Array Updates
192

193
When updating arrays, wrap values in arrays to specify per-trace values:
194

195
```javascript
196
// Update y data for multiple traces
197
await Plotly.restyle('chart', {
198
  'y': [
199
    [1, 2, 3, 4],      // Data for first trace
200
    [5, 6, 7, 8],      // Data for second trace  
201
    [9, 10, 11, 12]    // Data for third trace
202
  ]
203
}, [0, 1, 2]);
204

205
// Update single attribute for multiple traces
206
await Plotly.restyle('chart', {
207
  'marker.color': ['red', 'blue', 'green']  // Colors for three traces
208
}, [0, 1, 2]);
209
```
210

211
## Event Handling
212

213
Update functions emit specific events:
214

215
```javascript { .api }
216
interface UpdateEvents {
217
  'plotly_restyle': (eventData: RestyleEvent) => void;
218
  'plotly_relayout': (eventData: RelayoutEvent) => void;
219
  'plotly_update': (eventData: UpdateEvent) => void;
220
}
221

222
interface RestyleEvent {
223
  [attributePath: string]: any[];
224
}
225

226
interface RelayoutEvent {
227
  [attributePath: string]: any;
228
}
229

230
interface UpdateEvent {
231
  data: RestyleEvent;
232
  layout: RelayoutEvent;
233
}
234
```
235

236
**Usage Examples:**
237

238
```javascript
239
const chartDiv = document.getElementById('my-chart');
240

241
chartDiv.on('plotly_restyle', (eventData) => {
242
  console.log('Trace attributes changed:', eventData);
243
});
244

245
chartDiv.on('plotly_relayout', (eventData) => {
246
  console.log('Layout changed:', eventData);
247
  
248
  // Detect axis range changes (user zoom/pan)
249
  if (eventData['xaxis.range[0]'] !== undefined) {
250
    console.log('X-axis range changed');
251
  }
252
});
253
```
254

255
## Performance Tips
256

257
- Use `update()` instead of separate `restyle()` and `relayout()` calls when changing both
258
- Batch multiple attribute changes in a single call rather than multiple separate calls
259
- Use trace indices to limit updates to specific traces when possible
260
- Consider using `react()` for large-scale changes instead of multiple update calls
261

262
## Common Update Patterns
263

264
```javascript
265
// Toggle trace visibility
266
await Plotly.restyle('chart', {'visible': 'legendonly'}, [0]);
267
await Plotly.restyle('chart', {'visible': true}, [0]);
268

269
// Animate-like updates with smooth transitions
270
for (let i = 0; i < 100; i++) {
271
  const newY = data.map(d => d + Math.sin(i * 0.1));
272
  await Plotly.restyle('chart', {'y': [newY]}, [0]);
273
  await new Promise(resolve => setTimeout(resolve, 50));
274
}
275

276
// Conditional styling based on data
277
const colors = yData.map(y => y > threshold ? 'red' : 'blue');
278
await Plotly.restyle('chart', {'marker.color': [colors]}, [0]);
279

280
// Update axis range based on data
281
const maxY = Math.max(...yData);
282
await Plotly.relayout('chart', {'yaxis.range': [0, maxY * 1.1]});
283
```