Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 42 ยท Layout, Styling and Themes

Layout: Title, Size and Margins

Control the look of a Plotly figure with the layout object: titles and subtitles, width and height, autosize, margins, paper and plot backgrounds, and update_layout shortcuts.

The layout is everything in a figure that is not data: the title, the size, the margins, the colors of the background, the axes, the legend and the fonts. You already used it with update_layout. This chapter walks through the layout systematically, and this lesson starts with the outer frame: title, size, margins and backgrounds.

Understanding the layout is the difference between a default chart and a finished one that you can drop into a report or website.

The anatomy of a figure's surface

Two rectangles matter. The paper is the whole figure (the canvas, including titles and legend). The plot area is the inner rectangle where data is drawn, bounded by the axes. Margins are the space between the paper's edge and the plot area.

flowchart TD
    P["paper (the whole figure)<br/>paper_bgcolor, width, height"] --> M["margins<br/>l, r, t, b, pad"]
    P --> T["title, legend, colorbars"]
    P --> A["plot area<br/>plot_bgcolor"]
    A --> X["axes, grid, data"]

Two backgrounds: paper_bgcolor (whole figure) and plot_bgcolor (inside the axes).

Titles

The title is the most visible part of the layout. It is an object with its own properties, but a plain string also works:

Python Title, subtitle and position

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.

x and y position the title (in paper fractions from 0 to 1), xanchor says which part of the title text sits at x, and subtitle adds a smaller second line (Plotly 5.23 and later). In Express, title="..." does the same, and you can refine with update_layout(title_x=0.5).

Size: width, height and autosize

By default a figure autosizes: it fills its container's width, and takes a default height of 450 pixels. You can fix a size with width and height, or leave it responsive and only set the height:

Python
fig.update_layout(width=700, height=400)       # fixed size in pixels
fig.update_layout(height=400)                  # responsive width
fig.update_layout(autosize=True)               # default

A fixed width is good for exporting images (the saved PNG has exactly that size) and bad for web pages (it does not adapt to phones). Rule of thumb: leave the width free on the web, and set both only for export.

Margins

The default margins are 80 pixels on the left and right, 100 on top and 80 at the bottom. They leave space for the axis titles and the title. If you have a tight layout, or a chart that is cut off, change them:

Margins, backgrounds and a border

The margin object takes l, r, t, b and pad. Margins are in pixels, and plotly.js draws the plot area inside what remains. Set margin=dict(l=0, r=0, t=0, b=0) for a chart that fills its container completely, for example inside a card that already has a title. Note that if axis labels need more room than the margin offers, they get cut off, unless you enable automatic margins on the axis (automargin=True), which makes the margin grow to fit tick labels.

Backgrounds and colors

  • paper_bgcolor colors the whole figure; plot_bgcolor colors the area inside the axes.
  • Use "rgba(0,0,0,0)" (transparent) for both when the chart sits on a colored web page.
  • colorway is the list of colors used for traces in order, and is the easiest way to give charts a brand palette: fig.update_layout(colorway=["#0b6e4f", "#f4a261", "#264653"]).
  • font sets the default font (family, size, color) for every text element.
  • showlegend=False hides the legend, and hovermode sets how the tooltip behaves (details in a later lesson).
Python Size, margins, colorway and the full layout

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 layout dictionary only contains what you set. Everything else comes from the template, which supplies the defaults (the next lesson explains templates). Setting a property to None removes your explicit value, and the default returns.

Layout shortcuts to remember

Goal Code
Center the title fig.update_layout(title_x=0.5)
Chart with no whitespace fig.update_layout(margin=dict(l=0, r=0, t=0, b=0))
Transparent background fig.update_layout(paper_bgcolor="rgba(0,0,0,0)", plot_bgcolor="rgba(0,0,0,0)")
Brand colors fig.update_layout(colorway=[...])
One font everywhere fig.update_layout(font_family="Georgia", font_size=14)
Fixed size for a PNG fig.update_layout(width=900, height=500)

Common mistakes

  • Setting width for a web chart and then finding that it does not fit phones. Prefer a responsive width.
  • Cutting off axis titles with tiny margins. Use automargin=True on the axes, or give the margin room.
  • Putting a long title on one line over a narrow chart. Use <br> for line breaks ("Line one<br>line two") or the subtitle.
  • Expecting update_layout to replace a whole group. It merges into what is already there; pass overwrite=True to replace the group.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which property colors the area inside the axes?

    plot_bgcolor is the plot area; paper_bgcolor is the whole figure.
  2. 2. What does fig.update_layout(title_x=0.5) do?

    x positions the title as a fraction of the paper width, so 0.5 is the middle.
  3. 3. Which is the best choice for a chart on a responsive web page?

    Without a width, the chart fills the container; set only the height.
  4. 4. What is colorway?

    layout.colorway overrides the default trace color sequence of the template.
  5. 5. What happens if you set a layout property to None?

    None resets the property to the default.

Summary

  • The layout holds the title, size, margins, backgrounds, colorway and font; the template supplies defaults.
  • paper_bgcolor is the whole figure, plot_bgcolor the area inside the axes.
  • Leave the width free on the web; set width and height for exported images.
  • Margins (l, r, t, b) and automargin stop labels from being cut off.

Next: Colors and Color Scales