Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 42 ยท Subplots and Annotations

Subplots with make_subplots

Put several charts in one Plotly figure with make_subplots: grids, shared axes, column widths, spans, secondary y-axes, mixed chart types and per-subplot axis updates.

One chart answers one question. A dashboard row, a before/after comparison or a "price and volume" view needs several charts side by side, and often they must share an axis so that the eye can compare them. Plotly handles this with subplots: one figure that contains a grid of plotting areas, each with its own axes.

In Plotly Python you create the grid with plotly.subplots.make_subplots, add traces to chosen cells with row= and col=, and then style the figure as usual. Under the hood nothing magical happens: each cell is simply an extra pair of axes (xaxis2, yaxis2, ...) with a domain, the slice of the figure it occupies. Once you see that, every option in this lesson becomes easy to predict.

A simple grid

make_subplots(rows, cols) returns an empty figure with the axes already laid out. You add traces to a cell by passing its position (1-based, counted from the top-left).

Python Two charts in one figure

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The first trace sits on x/y, the second on x2/y2, and the two x-axes split the width of the figure with a gap in between. Subplot titles are ordinary annotations, which is why they appear in layout.annotations (see annotations and shapes).

Here is the same idea in Plotly.js, where you write the domains yourself. This is exactly what make_subplots generates for you.

The same layout by hand (Plotly.js)

Shared axes and sizes

Stacked charts that share a time axis should share the axis, so that zooming one zooms the others and the tick labels are not repeated.

  • shared_xaxes=True links the x-axes of a column, so zooming or panning moves them together. Use "columns", "rows" or "all" for finer control.
  • shared_yaxes=True does the same for y-axes of a row.
  • vertical_spacing and horizontal_spacing (fractions of the figure, 0 to 1) control the gaps.
  • row_heights and column_widths are relative sizes: row_heights=[0.7, 0.3] makes the top row 70 % of the height.
Python Price and volume with a shared x-axis

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice matches: Plotly links the axes with the matches property, so "shared" really means "these two axes always show the same range".

The specs grid: spans, types and secondary axes

For anything beyond a regular grid, pass specs: a list of rows, each a list of cell dictionaries (or None for an empty cell). Useful keys:

Key Meaning
colspan, rowspan The cell stretches over several columns or rows
type "xy" (default), "scene" (3D), "domain" (pie, sunburst, table), "polar", "geo", "mapbox"
secondary_y True adds a second y-axis on the right of that cell
l, r, t, b Extra padding around the cell

Trace types that are not Cartesian need a matching type: a pie chart lives in a domain cell and a 3D scatter in a scene cell. Forgetting this raises a clear error telling you which type the cell must have.

Python A wide chart over a pie and a dual-axis chart

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that the spanning cell {"colspan": 2} is followed by None in the same row: the second slot is covered by the span and must be declared empty.

Two y-axes with different scales invite misreading, because the crossing point of the lines is arbitrary. Use secondary_y only when the two series share the x-axis and a different unit, and always give each axis a title.

Styling one subplot

Axis-wide methods accept row and col, so you can change one cell without touching the others:

Python
fig.update_xaxes(title_text="Month", row=2, col=1)
fig.update_yaxes(range=[0, 100], row=1, col=2)
fig.update_xaxes(showgrid=False)          # all subplots at once

You can also add a whole figure's traces into a cell: fig.add_traces(other_fig.data, rows=1, cols=2), or loop over a list of traces and give each its own row and column.

A figure built with make_subplots is still a normal go.Figure. You can pass it to update_layout, export it, or animate it, and the grid becomes part of its JSON. The next lesson, on annotations and shapes, shows how to mark things up inside a cell.

flowchart LR
    A["make_subplots(rows, cols, specs)"] --> B["layout.xaxis, xaxis2, ... with domains"]
    A --> C["layout.yaxis, yaxis2, ... with domains"]
    D["add_trace(row, col)"] --> E["trace.xaxis = 'x2', trace.yaxis = 'y2'"]
    B --> F["One figure, many plot areas"]
    C --> F
    E --> F

Each cell is a pair of axes; the trace's row and col only decide which pair it uses.

Common mistakes

  • Counting from zero. row and col start at 1.
  • Wrong cell type. Pies, 3D and maps need type="domain", "scene" or "geo" in specs.
  • Too many subplots. More than about 12 cells becomes unreadable and slow. Consider facets built by Plotly Express.
  • Forgetting the height. The default 450 px is too small for three stacked rows; set height yourself.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which call adds a bar trace to the bottom-left cell of a 2 x 2 grid?

    Rows and columns are 1-based and counted from the top-left, so the bottom-left cell is row 2, column 1.
  2. 2. What does shared_xaxes=True really set up?

    Plotly links the axes with the matches property, and hides the repeated tick labels.
  3. 3. You want a pie chart in a subplot cell. What must the cell's spec contain?

    Pie, sunburst and table traces have no x/y axes. They need a domain cell.
  4. 4. In specs, why does a row with {"colspan": 2} need a None after it?

    The spec grid must still have one entry per column. The second slot is occupied by the span, so it is None.

Summary

  • make_subplots(rows, cols) creates a figure with a grid of axes; add_trace(..., row=, col=) picks the cell.
  • Each cell is an extra axis pair (xaxis2, yaxis2, ...) with a domain.
  • shared_xaxes, row_heights, column_widths and the spacing options control the layout.
  • specs adds spans, 3D/domain/polar cell types and secondary_y.
  • update_xaxes and update_yaxes accept row and col.

Next: Annotations, Shapes and Reference Lines