Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 42 ยท Layout, Styling and Themes

Legends, Fonts and Hover Labels

Customize the text of a Plotly chart: legend position, orientation and grouping, fonts and text sizes, hover modes, hovertemplate formatting, customdata, text labels and hover label styling.

The last layer of styling is the text that surrounds your data: the legend that explains colors, the fonts that everything is set in, and the hover labels that appear when the reader points at a mark. These three decide whether a chart can be understood without you standing next to it.

Hover labels are special for Plotly, because they are interactive: you can use them to show details that would clutter a static chart, such as names, units, formatted numbers and extra columns.

The legend

Express creates a legend for each trace that has a name. Control it through layout.legend and through trace properties:

Setting Effect
showlegend False hides the legend (layout) or one trace's entry (trace)
legend.title.text Heading above the entries
legend.orientation "v" (vertical, default) or "h"
legend.x, legend.y, xanchor, yanchor Position (paper fractions)
legend.bgcolor, bordercolor, borderwidth Box styling
legend.itemclick What a click does: "toggle" (default), "toggleothers" or False
legend.traceorder "normal", "reversed", "grouped"
legendgroup (trace) Link traces so that one entry controls all of them
legendgrouptitle (trace) Heading for a group of entries
name (trace) The text of the entry

Clicking a legend item hides or shows its trace, and double-clicking isolates it. For static exports, or when the legend wastes space, label the data directly (text on the last point, or annotations) and hide the legend.

Python Legend position, groups and click behavior

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 horizontal legend sits below the plot (y=-0.2 is outside the plot area, and yanchor="top" makes its top edge align there). Trace entries with the same legendgroup toggle together, so a "Target" line follows its "Actual" line. A trace with showlegend=False is still drawn, but gets no entry, which is the right choice for helper lines.

Fonts and text

Fonts are inherited. layout.font sets the default for everything, and the title, axes, legend and annotations can each override it:

Python
fig.update_layout(
    font=dict(family="Inter, Arial, sans-serif", size=14, color="#222"),
    title_font=dict(size=22),
    legend_font=dict(size=12),
)
fig.update_xaxes(tickfont=dict(size=11), title_font=dict(size=14))

Only fonts installed in the viewer's browser are used. Give a font stack ending with a generic family (sans-serif, serif, monospace) so there is always a fallback. For exported images, the machine that renders them needs the font too.

Text on the chart itself comes from the text property of a trace, together with mode="text" (scatter) or textposition (bars, scatter). texttemplate formats it, using the same %{...} syntax as hover templates, which we meet next. Text can also contain a small subset of HTML: <b>bold</b>, <i>italic</i>, <br> for line breaks, <sub>, <sup> and <a href> links.

Hover: modes and labels

The hovermode layout property controls how plotly.js finds the point to describe:

hovermode Behavior
"closest" The single nearest point (default for scatter)
"x" / "y" All points sharing the x (or y) of the cursor, in separate boxes
"x unified" / "y unified" One combined box listing every trace at that x, with a vertical line
False No hover

"x unified" is excellent for time series with several lines, because you read all values at once. Style the boxes with hoverlabel (bgcolor, font, bordercolor, align, namelength).

hovertemplate

By default the tooltip shows x, y and the trace name. hovertemplate gives you the full control: write a string with %{variable} placeholders and optional d3 formats after a colon.

Placeholder Value
%{x}, %{y}, %{z} The point's coordinates
%{y:.2f}, %{y:$,.0f}, `%{x %b %Y}`
%{text}, %{label}, %{value} The trace's text or pie properties
%{customdata[0]} A column of extra data you attach with customdata
%{percent} Pie shares
<extra>...</extra> The secondary box (default: the trace name). <extra></extra> hides it.
A hovertemplate with customdata

The customdata array holds one small array per bar (year, country code). In the template, %{customdata[1]} picks the country code. The y value is formatted with ,.0f, a thousands separator and no decimals.

In Express, hover_name becomes the bold title, hover_data adds columns (with formats), and custom_data stores columns for your own hovertemplate:

Python Hover control in Express

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.

In hover_data a string format (":,.0f") formats the value, False hides a column, and True shows an extra column with its default format. After building the chart you can override everything with update_traces(hovertemplate=...), as shown.

Tips for good tooltips

  • Show the name of the thing first (country, product), then the numbers with units and sensible rounding.
  • Use <extra></extra> to remove the trace name box when it only repeats information.
  • Use hovermode="x unified" for time series; "closest" for scatter plots.
  • Do not put long paragraphs in a tooltip; people read them for a second.
  • Hide tooltips on decoration traces with hoverinfo="skip".

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. How do you make two traces toggle together when one legend entry is clicked?

    Traces sharing a legend group are shown or hidden together.
  2. 2. Which hovermode shows all traces at the cursor's x in one box?

    x unified combines all values at that x into one label with a guide line.
  3. 3. What does <extra></extra> do in a hovertemplate?

    The extra box defaults to the trace name; leaving it empty removes it.
  4. 4. How do you display a value as a dollar amount with a thousands separator in a hover template?

    After the colon you give a d3 format, such as $,.0f.
  5. 5. Where do the extra columns referenced as %{customdata[0]} come from?

    customdata carries any extra per-point values to use in hover templates and click events.

Summary

  • The legend is configured through layout.legend (position, orientation, click behavior) and trace properties (name, legendgroup, showlegend).
  • Fonts inherit from layout.font and can be overridden per element; always add a generic fallback family.
  • hovermode decides what is picked; hovertemplate formats the text with %{...} and d3 formats; customdata adds extra values.
  • Express offers hover_name, hover_data and custom_data for the same purpose.

Next: Subplots with make_subplots