Custom Hover Templates in Plotly: Make Tooltips Speak

Why the default hover text is often not enough

When you first build an interactive chart with Plotly, the tooltip that pops up when you hover over a point looks like this: X: 5
Y: 12.3. It’s quick, but it can be vague. In a business dashboard you might need units, dates, or derived metrics. The default hover text shows only the raw data fields, and you can’t control formatting or add context. That’s where hovertemplate comes in.

Enter Plotly’s hovertemplate

Hovertemplate is a string that replaces the default tooltip. It can contain literal text, %{variable} placeholders, and HTML tags. Because it’s a template, you can format numbers, add newlines, and even style parts of the text.

How the syntax works

Placeholders are case‑sensitive and follow the pattern %{field[:format]}. Common fields include x, y, text, and customdata. The optional :format part uses Python‑style formatting (e.g., .2f for two decimal places). You can also use %{date|%Y-%m-%d} to format dates.

Crafting a multi‑line, unit‑annotated tooltip

Suppose you want a tooltip that reads:

• Timestamp: 2026‑10‑16 08:00
• Value: 12.34 USD
• Growth: +3.2 %

You can achieve that with the following template:

hovertemplate = "Timestamp: %{x|%Y-%m-%d %H:%M}
Value: %{y:.2f} USD
Growth: %{customdata:.1f}%"

Cross‑language consistency

The same syntax works in Plotly’s JavaScript, Python, and R APIs. Only the surrounding code changes. In JavaScript you set hovertemplate inside the trace object; in Python you pass it to px.scatter(..., hovertemplate=…) or set it on the figure’s layout.

Hands‑on example: a growth‑rate scatter plot

Below is a minimal Python example that demonstrates the technique. The data set contains a timestamp, a measured value, and a pre‑computed growth percentage stored in customdata.

import plotly.express as px
import pandas as pd

# Sample data

data = pd.DataFrame({
    "time": pd.date_range(start="2026-10-01", periods=5, freq="D"),
    "value": [10.0, 10.5, 11.2, 11.8, 12.4],
    "growth": [0.0, 5.0, 7.0, 4.5, 3.2]  # percent growth
})

fig = px.scatter(
    data,
    x="time",
    y="value",
    custom_data=[data["growth"]],
    hovertemplate="Timestamp: %{x|%Y-%m-%d}
Value: %{y:.2f} USD
Growth: %{customdata:.1f}%"
)
fig.update_traces(marker=dict(size=10, color="steelblue"))
fig.update_layout(title="Growth‑rate Scatter Plot", xaxis_title="Date", yaxis_title="Value (USD)")
fig.show()

When you hover over a point, the tooltip now displays the three lines above, with proper units and formatting.

Trade‑offs and practical limits

• Verbosity: A complex template can become long and hard to maintain, especially if you need to reference many custom fields.
• Performance: For traces with hundreds of thousands of points, rendering the template for every hover event can add latency.
• Browser quirks: Some browsers truncate HTML inside the tooltip if the container’s CSS limits overflow. Test in Chrome and Firefox to ensure consistency.
• Version requirement: Hovertemplate is only available in Plotly 4.0 and newer. Verify your environment with plotly.__version__.

What to check after you deploy

1. Syntax validation: A typo like %{Y} will be ignored, resulting in a blank field. Run a quick hover test to confirm all placeholders resolve.
2. Cross‑browser rendering: Open the chart in at least two major browsers and hover over several points.
3. Performance audit: For large datasets, use the browser’s performance panel to monitor hover event time.
4. Accessibility: Ensure the tooltip text is readable by screen readers; avoid excessive HTML.

With these checks in place, you’ll have a tooltip that delivers the exact information your users need, without cluttering the chart.

Actionable takeaway

Replace the default hover text by setting hovertemplate on your traces. Keep the template concise, test across browsers, and remember that performance can degrade with very large traces. Once you’re comfortable, you can add more context—such as category labels or computed statistics—right inside the tooltip, turning a simple chart into a powerful data story.