0
# Layout Configuration
1

2
Comprehensive layout options for customizing plot appearance, axes, legends, annotations, and interactive components.
3

4
## Capabilities
5

6
### Basic Layout Properties
7

8
Core layout configuration for plot dimensions, colors, and fonts.
9

10
```javascript { .api }
11
/**
12
 * Basic layout configuration
13
 */
14
interface BasicLayout {
15
  title?: string | Partial<Title>;
16
  width?: number;
17
  height?: number;
18
  autosize?: boolean;
19
  margin?: Partial<Margin>;
20
  paper_bgcolor?: string;
21
  plot_bgcolor?: string;
22
  font?: Partial<Font>;
23
  separators?: string;
24
  hidesources?: boolean;
25
  showlegend?: boolean;
26
}
27

28
interface Title {
29
  text: string;
30
  font?: Partial<Font>;
31
  x?: number;
32
  y?: number;
33
  xref?: string;
34
  yref?: string;
35
  xanchor?: 'auto' | 'left' | 'center' | 'right';
36
  yanchor?: 'auto' | 'top' | 'middle' | 'bottom';
37
  pad?: Partial<Padding>;
38
}
39

40
interface Margin {
41
  l?: number;
42
  r?: number;
43
  t?: number;
44
  b?: number;
45
  pad?: number;
46
  autoexpand?: boolean;
47
}
48

49
interface Font {
50
  family?: string;
51
  size?: number;
52
  color?: string;
53
}
54

55
interface Padding {
56
  t?: number;
57
  r?: number;
58
  b?: number;
59
  l?: number;
60
}
61
```
62

63
**Usage Examples:**
64

65
```javascript
66
// Basic layout configuration
67
Plotly.newPlot('myDiv', data, {
68
    title: 'My Chart Title',
69
    width: 800,
70
    height: 600,
71
    margin: { l: 50, r: 50, t: 80, b: 50 },
72
    paper_bgcolor: 'white',
73
    plot_bgcolor: '#f8f9fa',
74
    font: {
75
        family: 'Arial, sans-serif',
76
        size: 12,
77
        color: '#333'
78
    }
79
});
80

81
// Advanced title configuration
82
Plotly.newPlot('myDiv', data, {
83
    title: {
84
        text: 'Advanced Title with Styling',
85
        x: 0.5,
86
        y: 0.95,
87
        xanchor: 'center',
88
        font: {
89
            size: 24,
90
            color: 'blue'
91
        }
92
    }
93
});
94
```
95

96
### Axis Configuration
97

98
Comprehensive axis customization for Cartesian coordinate systems.
99

100
```javascript { .api }
101
/**
102
 * Axis configuration for x and y axes
103
 */
104
interface Axis {
105
  title?: string | Partial<AxisTitle>;
106
  type?: 'linear' | 'log' | 'date' | 'category' | 'multicategory';
107
  autorange?: boolean | 'reversed';
108
  range?: [any, any];
109
  fixedrange?: boolean;
110
  scaleanchor?: string;
111
  scaleratio?: number;
112
  constrain?: 'range' | 'domain';
113
  constraintoward?: 'left' | 'center' | 'right' | 'top' | 'middle' | 'bottom';
114
  
115
  // Ticks
116
  tickmode?: 'linear' | 'array';
117
  nticks?: number;
118
  tick0?: number;
119
  dtick?: number | string;
120
  tickvals?: any[];
121
  ticktext?: string[];
122
  ticks?: '' | 'outside' | 'inside';
123
  ticklen?: number;
124
  tickwidth?: number;
125
  tickcolor?: string;
126
  tickfont?: Partial<Font>;
127
  tickangle?: number;
128
  tickformat?: string;
129
  tickformatstops?: TickFormatStop[];
130
  
131
  // Grid and lines
132
  showgrid?: boolean;
133
  gridwidth?: number;
134
  gridcolor?: string;
135
  showline?: boolean;
136
  linewidth?: number;
137
  linecolor?: string;
138
  showspikes?: boolean;
139
  spikecolor?: string;
140
  spikethickness?: number;
141
  spikedash?: string;
142
  spikemode?: string;
143
  spikesnap?: string;
144
  
145
  // Zero line
146
  zeroline?: boolean;
147
  zerolinewidth?: number;
148
  zerolinecolor?: string;
149
  
150
  // Labels and positioning
151
  showticklabels?: boolean;
152
  side?: 'top' | 'bottom' | 'left' | 'right';
153
  overlaying?: string;
154
  position?: number;
155
  anchor?: string;
156
  domain?: [number, number];
157
  
158
  // Category-specific
159
  categoryorder?: 'trace' | 'category ascending' | 'category descending' | 'array';
160
  categoryarray?: any[];
161
}
162

163
interface AxisTitle {
164
  text: string;
165
  font?: Partial<Font>;
166
  standoff?: number;
167
}
168

169
interface TickFormatStop {
170
  enabled?: boolean;
171
  dtickrange?: [any, any];
172
  value?: string;
173
}
174
```
175

176
**Usage Examples:**
177

178
```javascript
179
// Basic axis configuration
180
Plotly.newPlot('myDiv', data, {
181
    xaxis: {
182
        title: 'Time',
183
        type: 'date',
184
        showgrid: true,
185
        gridcolor: '#e6e6e6'
186
    },
187
    yaxis: {
188
        title: {
189
            text: 'Value',
190
            font: { size: 16, color: 'blue' }
191
        },
192
        type: 'linear',
193
        range: [0, 100]
194
    }
195
});
196

197
// Log scale with custom ticks
198
Plotly.newPlot('myDiv', data, {
199
    yaxis: {
200
        type: 'log',
201
        tickmode: 'array',
202
        tickvals: [1, 10, 100, 1000],
203
        ticktext: ['1', '10', '100', '1K']
204
    }
205
});
206

207
// Multiple y-axes
208
Plotly.newPlot('myDiv', data, {
209
    yaxis: {
210
        title: 'Primary Y-Axis',
211
        side: 'left'
212
    },
213
    yaxis2: {
214
        title: 'Secondary Y-Axis',
215
        side: 'right',
216
        overlaying: 'y'
217
    }
218
});
219
```
220

221
### Legend Configuration
222

223
Legend positioning, styling, and behavior options.
224

225
```javascript { .api }
226
/**
227
 * Legend configuration
228
 */
229
interface Legend {
230
  bgcolor?: string;
231
  bordercolor?: string;
232
  borderwidth?: number;
233
  font?: Partial<Font>;
234
  orientation?: 'v' | 'h';
235
  traceorder?: 'normal' | 'reversed' | 'grouped' | 'reversed+grouped';
236
  tracegroupgap?: number;
237
  itemsizing?: 'trace' | 'constant';
238
  itemwidth?: number;
239
  itemclick?: 'toggle' | 'toggleothers' | false;
240
  itemdoubleclick?: 'toggle' | 'toggleothers' | false;
241
  
242
  // Positioning
243
  x?: number;
244
  y?: number;
245
  xanchor?: 'auto' | 'left' | 'center' | 'right';
246
  yanchor?: 'auto' | 'top' | 'middle' | 'bottom';
247
  
248
  // Grouping
249
  grouptitlefont?: Partial<Font>;
250
  
251
  // Visibility
252
  visible?: boolean;
253
}
254
```
255

256
**Usage Examples:**
257

258
```javascript
259
// Basic legend configuration
260
Plotly.newPlot('myDiv', data, {
261
    showlegend: true,
262
    legend: {
263
        x: 1,
264
        y: 1,
265
        xanchor: 'right',
266
        yanchor: 'top',
267
        bgcolor: 'rgba(255,255,255,0.8)',
268
        bordercolor: '#333',
269
        borderwidth: 1
270
    }
271
});
272

273
// Horizontal legend at bottom
274
Plotly.newPlot('myDiv', data, {
275
    legend: {
276
        orientation: 'h',
277
        x: 0.5,
278
        y: -0.1,
279
        xanchor: 'center',
280
        yanchor: 'top'
281
    }
282
});
283
```
284

285
### Annotations
286

287
Text annotations with arrows and flexible positioning.
288

289
```javascript { .api }
290
/**
291
 * Annotation configuration
292
 */
293
interface Annotation {
294
  text: string;
295
  font?: Partial<Font>;
296
  width?: number;
297
  height?: number;
298
  opacity?: number;
299
  align?: 'left' | 'center' | 'right';
300
  valign?: 'top' | 'middle' | 'bottom';
301
  bgcolor?: string;
302
  bordercolor?: string;
303
  borderpad?: number;
304
  borderwidth?: number;
305
  
306
  // Positioning
307
  x?: any;
308
  y?: any;
309
  xref?: string;
310
  yref?: string;
311
  xanchor?: 'auto' | 'left' | 'center' | 'right';
312
  yanchor?: 'auto' | 'top' | 'middle' | 'bottom';
313
  xshift?: number;
314
  yshift?: number;
315
  
316
  // Arrow
317
  showarrow?: boolean;
318
  arrowcolor?: string;
319
  arrowhead?: number;
320
  startarrowhead?: number;
321
  arrowside?: 'end' | 'start' | 'end+start' | 'none';
322
  arrowsize?: number;
323
  startarrowsize?: number;
324
  arrowwidth?: number;
325
  standoff?: number;
326
  startstandoff?: number;
327
  ax?: number;
328
  ay?: number;
329
  axref?: string;
330
  ayref?: string;
331
  
332
  // Click behavior
333
  clicktoshow?: false | 'onoff' | 'onout';
334
  captureevents?: boolean;
335
}
336
```
337

338
**Usage Examples:**
339

340
```javascript
341
// Basic text annotation
342
Plotly.newPlot('myDiv', data, {
343
    annotations: [{
344
        text: 'Peak Value',
345
        x: 3,
346
        y: 25,
347
        showarrow: true,
348
        arrowhead: 2,
349
        arrowcolor: 'red'
350
    }]
351
});
352

353
// Multiple annotations with different styles
354
Plotly.newPlot('myDiv', data, {
355
    annotations: [
356
        {
357
            text: 'Start',
358
            x: 0,
359
            y: 0,
360
            xref: 'x',
361
            yref: 'y',
362
            showarrow: false,
363
            bgcolor: 'yellow',
364
            bordercolor: 'black'
365
        },
366
        {
367
            text: 'End',
368
            x: 10,
369
            y: 20,
370
            showarrow: true,
371
            ax: -40,
372
            ay: -40
373
        }
374
    ]
375
});
376
```
377

378
### Shapes
379

380
Geometric shapes for highlighting regions and adding visual elements.
381

382
```javascript { .api }
383
/**
384
 * Shape configuration
385
 */
386
interface Shape {
387
  type: 'circle' | 'rect' | 'path' | 'line';
388
  visible?: boolean;
389
  layer?: 'below' | 'above';
390
  opacity?: number;
391
  fillcolor?: string;
392
  fillrule?: 'evenodd' | 'nonzero';
393
  
394
  // Line properties
395
  line?: {
396
    color?: string;
397
    width?: number;
398
    dash?: string;
399
  };
400
  
401
  // Positioning
402
  x0?: any;
403
  y0?: any;
404
  x1?: any;
405
  y1?: any;
406
  xref?: string;
407
  yref?: string;
408
  
409
  // Path-specific
410
  path?: string;
411
  
412
  // Template
413
  name?: string;
414
  templateitemname?: string;
415
}
416
```
417

418
**Usage Examples:**
419

420
```javascript
421
// Rectangle shape
422
Plotly.newPlot('myDiv', data, {
423
    shapes: [{
424
        type: 'rect',
425
        x0: 1,
426
        y0: 0,
427
        x1: 3,
428
        y1: 20,
429
        fillcolor: 'rgba(255, 0, 0, 0.3)',
430
        line: {
431
            color: 'red',
432
            width: 2
433
        },
434
        layer: 'below'
435
    }]
436
});
437

438
// Line shape
439
Plotly.newPlot('myDiv', data, {
440
    shapes: [{
441
        type: 'line',
442
        x0: 0,
443
        y0: 15,
444
        x1: 10,
445
        y1: 15,
446
        line: {
447
            color: 'green',
448
            width: 3,
449
            dash: 'dash'
450
        }
451
    }]
452
});
453
```
454

455
### Images
456

457
Embedded images with flexible positioning and sizing.
458

459
```javascript { .api }
460
/**
461
 * Image configuration
462
 */
463
interface Image {
464
  source: string;
465
  visible?: boolean;
466
  opacity?: number;
467
  
468
  // Positioning
469
  x?: any;
470
  y?: any;
471
  xref?: string;
472
  yref?: string;
473
  xanchor?: 'left' | 'center' | 'right';
474
  yanchor?: 'top' | 'middle' | 'bottom';
475
  
476
  // Sizing
477
  sizex?: number;
478
  sizey?: number;
479
  sizing?: 'fill' | 'contain' | 'stretch';
480
  
481
  // Layer
482
  layer?: 'below' | 'above';
483
  
484
  // Template
485
  name?: string;
486
  templateitemname?: string;
487
}
488
```
489

490
**Usage Examples:**
491

492
```javascript
493
// Add logo to plot
494
Plotly.newPlot('myDiv', data, {
495
    images: [{
496
        source: 'https://example.com/logo.png',
497
        x: 0.9,
498
        y: 0.9,
499
        sizex: 0.2,
500
        sizey: 0.2,
501
        xref: 'paper',
502
        yref: 'paper',
503
        xanchor: 'right',
504
        yanchor: 'top'
505
    }]
506
});
507
```
508

509
### Interactive Components
510

511
Update menus, sliders, and range selectors for interactive plots.
512

513
```javascript { .api }
514
/**
515
 * Update menu configuration
516
 */
517
interface UpdateMenu {
518
  type?: 'dropdown' | 'buttons';
519
  direction?: 'left' | 'right' | 'up' | 'down';
520
  active?: number;
521
  showactive?: boolean;
522
  buttons: UpdateMenuButton[];
523
  
524
  // Positioning
525
  x?: number;
526
  y?: number;
527
  xanchor?: 'auto' | 'left' | 'center' | 'right';
528
  yanchor?: 'auto' | 'top' | 'middle' | 'bottom';
529
  
530
  // Styling
531
  bgcolor?: string;
532
  bordercolor?: string;
533
  borderwidth?: number;
534
  font?: Partial<Font>;
535
  
536
  // Padding
537
  pad?: Partial<Padding>;
538
}
539

540
interface UpdateMenuButton {
541
  label?: string;
542
  method?: 'restyle' | 'relayout' | 'update' | 'animate';
543
  args?: any[];
544
  args2?: any[];
545
  visible?: boolean;
546
}
547

548
/**
549
 * Slider configuration
550
 */
551
interface Slider {
552
  active?: number;
553
  steps: SliderStep[];
554
  
555
  // Positioning
556
  x?: number;
557
  y?: number;
558
  len?: number;
559
  xanchor?: 'auto' | 'left' | 'center' | 'right';
560
  yanchor?: 'auto' | 'top' | 'middle' | 'bottom';
561
  
562
  // Styling
563
  bgcolor?: string;
564
  bordercolor?: string;
565
  borderwidth?: number;
566
  tickcolor?: string;
567
  ticklen?: number;
568
  tickwidth?: number;
569
  
570
  // Current value
571
  currentvalue?: {
572
    visible?: boolean;
573
    prefix?: string;
574
    suffix?: string;
575
    xanchor?: 'left' | 'center' | 'right';
576
    offset?: number;
577
    font?: Partial<Font>;
578
  };
579
  
580
  // Transition
581
  transition?: {
582
    duration?: number;
583
    easing?: string;
584
  };
585
}
586

587
interface SliderStep {
588
  label?: string;
589
  method?: 'restyle' | 'relayout' | 'update' | 'animate';
590
  args?: any[];
591
  visible?: boolean;
592
  execute?: boolean;
593
}
594
```
595

596
**Usage Examples:**
597

598
```javascript
599
// Dropdown menu for changing chart type
600
Plotly.newPlot('myDiv', data, {
601
    updatemenus: [{
602
        type: 'dropdown',
603
        x: 0.1,
604
        y: 1.15,
605
        buttons: [
606
            {
607
                label: 'Line',
608
                method: 'restyle',
609
                args: [{'type': 'scatter', 'mode': 'lines'}]
610
            },
611
            {
612
                label: 'Bar',
613
                method: 'restyle',
614
                args: [{'type': 'bar'}]
615
            }
616
        ]
617
    }]
618
});
619

620
// Slider for data filtering
621
Plotly.newPlot('myDiv', data, {
622
    sliders: [{
623
        active: 0,
624
        currentvalue: {
625
            prefix: 'Year: '
626
        },
627
        steps: [
628
            {
629
                label: '2020',
630
                method: 'restyle',
631
                args: [{'visible': [true, false, false]}]
632
            },
633
            {
634
                label: '2021',
635
                method: 'restyle',
636
                args: [{'visible': [false, true, false]}]
637
            }
638
        ]
639
    }]
640
});
641
```
642

643
## Subplot Configuration
644

645
### Multiple Subplot Types
646

647
```javascript { .api }
648
/**
649
 * Grid configuration for subplots
650
 */
651
interface Grid {
652
  rows?: number;
653
  columns?: number;
654
  subplots?: string[][];
655
  xaxes?: string[];
656
  yaxes?: string[];
657
  roworder?: 'top to bottom' | 'bottom to top';
658
  pattern?: 'independent' | 'coupled';
659
  xgap?: number;
660
  ygap?: number;
661
  domain?: {
662
    x?: [number, number];
663
    y?: [number, number];
664
  };
665
  xside?: 'bottom' | 'bottom plot' | 'top plot' | 'top';
666
  yside?: 'left' | 'left plot' | 'right plot' | 'right';
667
}
668
```
669

670
**Usage Examples:**
671

672
```javascript
673
// 2x2 subplot grid
674
Plotly.newPlot('myDiv', data, {
675
    grid: {
676
        rows: 2,
677
        columns: 2,
678
        pattern: 'independent'
679
    },
680
    xaxis: { title: 'X1' },
681
    xaxis2: { title: 'X2' },
682
    xaxis3: { title: 'X3' },
683
    xaxis4: { title: 'X4' },
684
    yaxis: { title: 'Y1' },
685
    yaxis2: { title: 'Y2' },
686
    yaxis3: { title: 'Y3' },
687
    yaxis4: { title: 'Y4' }
688
});
689
```