Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 42 ยท Interactivity and Animation

Hover, Click and Events

Control Plotly tooltips with hovertemplate, hovermode and customdata, then react to hover, click, selection and zoom events with Plotly.js and Dash.

Interactivity is the reason to choose Plotly over a static image library. Out of the box, a figure already shows tooltips, zooms, pans, selects and toggles legend entries. This lesson shows how to shape those behaviors: what the tooltip says, how it is triggered, and how your own code can react when the user hovers, clicks, selects or zooms.

Hover text: hoverinfo, hover_name and hovertemplate

Every trace has a tooltip. Three levels of control exist, from quick to complete.

  1. hover_name and hover_data in Plotly Express: pick the column used as the bold title and extra columns to show.
  2. hoverinfo on a trace: choose which parts appear ("x+y", "text", "name", "none" to turn the tooltip off, "skip" to disable hover events as well).
  3. hovertemplate: write the whole tooltip as a template string, using %{x}, %{y}, %{text}, %{customdata[0]} and d3-style formatting such as %{y:.1f}, %{y:$,.0f} or %{x|%b %Y} for dates.

The secondary box <extra></extra> removes the trace name that Plotly would otherwise print next to the tooltip.

Python A hovertemplate with customdata

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.

customdata is how you carry extra columns into the tooltip and into click events (below). It can be a 2D array: one row per point, one column per extra field. With px, pass custom_data=[...] as above; with graph_objects, pass customdata= yourself.

hovermode: which points does a tooltip cover?

layout.hovermode decides how the cursor finds data:

Value Behavior
"closest" One tooltip for the nearest point (default for scatter)
"x" A tooltip for every trace at the cursor's x position (default for bars with px)
"x unified" One combined tooltip for all traces, with a vertical spike line: ideal for time series
"y", "y unified" The same for y
False Hover disabled

hoverdistance controls how close the cursor must be (pixels), and spikemode="across" on an axis draws crosshair lines to the axes. Together they make dense time series pleasant to read.

Unified hover with a spike line (Plotly.js)

Events in Plotly.js

Plotly.js emits events on the chart's <div>. You listen with gd.on("event", handler). The important ones:

  • plotly_hover and plotly_unhover: the cursor enters or leaves a point.
  • plotly_click: the user clicks a point. data.points[0] has x, y, curveNumber, pointNumber and customdata.
  • plotly_selected and plotly_deselect: box or lasso selection (dragmode: "select" or "lasso").
  • plotly_relayout: the layout changed (zoom, pan, camera move). The event data lists the changed properties, such as xaxis.range[0].
  • plotly_restyle, plotly_legendclick, plotly_doubleclick, plotly_animated: more specialized.
Click and select events

The handler runs in the browser, so you can update other page elements, call an API, or change another chart with Plotly.restyle. Remember to remove listeners (gd.removeAllListeners("plotly_click")) before you redraw in a single-page app, otherwise handlers pile up.

Events with Dash and notebooks

In Dash, you do not write JavaScript listeners. A dcc.Graph exposes the same events as properties: hoverData, clickData, selectedData and relayoutData. A callback that takes Input("graph", "clickData") runs when the user clicks, and receives a dictionary like {"points": [{"x": ..., "y": ..., "customdata": [...]}]}. That is why customdata matters: it is the reliable way to learn which row of your DataFrame was clicked. You will use this in Dash callbacks and live graphs.

In Jupyter, go.FigureWidget gives Python callbacks directly: fig.data[0].on_click(fn), on_hover(fn) and on_selection(fn).

sequenceDiagram
    participant U as User
    participant G as Graph (browser)
    participant H as Your handler
    U->>G: click a point
    G->>H: plotly_click with points[0]
    H->>G: Plotly.restyle / update page
    G-->>U: updated view

The chart reports what was clicked; your handler decides what to change.

Configuring the modebar and interactions

Besides events, you control which interactions exist:

  • layout.dragmode: "zoom", "pan", "select", "lasso" or False.
  • config={"displayModeBar": False} hides the toolbar; "scrollZoom": True enables wheel zoom (off by default in 2D); "staticPlot": True turns the chart into an image.
  • xaxis.fixedrange=True locks an axis against zoom, which is useful on phones, where accidental zooming is annoying.
  • layout.clickmode="event+select" lets a click both fire an event and select the point.

On touch screens a tooltip appears on tap. Keep hover text short and move long explanations into the page next to the chart, where they can be read without covering the data.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which hovertemplate removes the trace name shown beside the tooltip?

    The extra box shows the trace name by default. An empty <extra></extra> removes it.
  2. 2. Which hovermode is best for a time series with several lines?

    x unified shows one tooltip with every trace's value at that x and draws a spike line.
  3. 3. How do you learn which DataFrame row a user clicked?

    customdata travels with each point into hover templates and click events, so an id or key survives.
  4. 4. In Dash, where do you find the point a user clicked on a dcc.Graph?

    dcc.Graph exposes hoverData, clickData, selectedData and relayoutData as properties usable as callback inputs.

Summary

  • Shape tooltips with hover_name, hoverinfo and especially hovertemplate plus customdata.
  • hovermode (closest, x, x unified) controls how points are found; spikes add crosshairs.
  • Plotly.js raises plotly_hover, plotly_click, plotly_selected and plotly_relayout; attach with gd.on.
  • Dash maps those events to hoverData, clickData, selectedData and relayoutData.
  • Tune dragmode, config and fixedrange to decide what users may do.

Next: Dropdown Menus and Buttons