How to Add Line Breaks in Plotly LaTeX Labels: Stack α and β on Separate Lines Using a Matrix

Learn a reliable way to create multiline LaTeX in Plotly axis titles: avoid Python escaping pitfalls and use a single $...$ matrix to stack symbols like α and β.

Getting a clean line break inside math mode text in Plotly can be unexpectedly tricky. At first glance it looks like a simple LaTeX task, but in practice it blends Python string escaping, Plotly’s LaTeX parsing rules, and the constraints of LaTeX math mode. If you fix only one of these layers, the result still won’t work. Below is a practical walkthrough that demonstrates the failure modes and a reliable way to stack symbols like α and β on separate lines.

The problem, in code

The following minimal setup attempts different ways to insert a line break between α and β. None of them succeeds for different reasons.

import plotly.graph_objects as gobj
canvas = gobj.Figure()
canvas.add_trace(gobj.Box(y=[10, 14]))
canvas.update_layout(xaxis_title="$\alpha \\ \beta$")  # causes to_image error
# canvas.update_layout(xaxis_title=r"$\alpha \\ \beta$")  # no breaks between math shape of alpha and beta
# canvas.update_layout(xaxis_title="$\alpha$<br>$\beta$")  # only shows math shape of alpha and no beta at all!
# canvas.update_layout(xaxis_title="$\alpha \\ \beta$")  # no breaks between math shape of alpha and beta
# canvas.update_layout(xaxis_title="$$\alpha \\ \beta$$")  # no breaks between math shape of alpha and beta
# canvas.update_layout(xaxis_title="$$\alpha$$ <br> $$\beta$$")  # only shows math shape of alpha and no beta at all!
canvas.show()
canvas.write_image("this_image.pdf")

Why it fails

There are several overlapping pitfalls here. Solving only one isn’t enough; all must be handled together to get a proper line break.

The first layer is Python escaping. You need to pass a string that literally contains sequences like \alpha and \\ to Plotly. In Python, '\alpha' is not what it looks like: \a is a control character, so '\alpha' becomes a bell followed by "lpha". Likewise, "\\" represents a single backslash character. That’s why writing plain "\alpha" or "\\" inside a normal string won’t produce the intended LaTeX input. You either escape each backslash in a normal string, like "\\alpha \\\\ \\beta", or use a raw string r"..." so backslashes are preserved as-is.

The second layer is how Plotly treats LaTeX input. Only labels that start and end with a single pair of dollar signs are parsed as LaTeX. You cannot split the math across multiple $...$ segments or mix separate math blocks with HTML breaks. Attempts such as "$\alpha$<br>$\beta$" or "$$\alpha$$ <br> $$\beta$$" won’t work as intended.

The third layer is LaTeX math mode itself. Inside $...$ you cannot insert a line break with \\ arbitrarily. Line breaks are allowed only in specific environments and contexts. Common text-mode constructs like HTML <br> or freeform \\ do not act as generic line breaks in math mode. Environments such as align support \\ for splitting lines, but you cannot switch into align within the single inline math context enforced by Plotly’s $...$ wrapper.

The fix

A straightforward way to stack symbols vertically without leaving math mode is to use a matrix. This stays fully within a single $...$ and makes \\ valid because it’s inside an environment that supports row breaks. The key is to pass the correct literal LaTeX string to Plotly, ensuring Python doesn’t eat the backslashes on the way.

import plotly.graph_objects as gobj
chart = gobj.Figure()
chart.add_trace(gobj.Box(y=[10, 14]))
chart.update_layout(xaxis_title=r"$\begin{matrix}\alpha\\ \beta\end{matrix}$")
chart.show()
chart.write_image("this_image.pdf")

This renders α on the first line and β on the second line in the axis title, and works for both on-screen display and when exporting with write_image.

Why this matters

Labels often carry semantic weight in analytics dashboards and research plots, and math typesetting is part of that. When Python escaping, Plotly’s LaTeX boundary rules, and LaTeX math-mode constraints collide, errors can be confusing. Understanding how these layers interact makes the failure modes predictable and the fix systematic, rather than a series of blind guesses.

Conclusion

To reliably add a line break in Plotly’s math-mode labels, pass a correctly escaped LaTeX string within a single pair of dollar signs and use a construct that allows line breaks inside math mode. A small matrix is a simple and effective choice. Keep an eye on Python string literals, avoid splitting math across multiple $ blocks or mixing HTML breaks, and pick a math environment where \\ is legal. With that, multi-line LaTeX labels behave consistently in both interactive and exported figures.