Point selection handling
Inspect which plotted points a user clicked in a notebook.
Plotly · Function
callback
Registers a callback for clicks on one or more points in a Plotly trace. It is intended for traces displayed through FigureWidget in an ipywidget context.
How it works
This method registers a callable for point-click events on a trace. The handler receives the trace, a Points object containing selected indices, and an InputDeviceState object; setting append=True preserves existing handlers instead of replacing them.
Syntax
trace.on_click(callback, append=False)Parameters
| Name | Type | Description |
|---|---|---|
callback | Callable | Function called for point-click events; it receives the trace, a Points object, and an InputDeviceState object. |
append | bool | When True, append the handler to existing on_click callbacks; when False, replace them. |
Returns
None
Key points
- on_click attaches a function to point-click events for the trace.
- The handler must accept three positional arguments.
- The second argument is a Points object containing click-selection information.
- The third argument describes the input-device state.
- append=True allows multiple click handlers to coexist.
Common mistakes
- The trace must belong to a FigureWidget for the callback to fire.
- The FigureWidget also has to be displayed in an ipywidget context.
- Using plot or iplot does not trigger this callback.
- The default append=False replaces earlier handlers; use append=True to retain them.
Example: Handle point clicks
import plotly.graph_objects as go
fig = go.FigureWidget([go.Scatter(x=[1, 2], y=[3, 0])])
def click_fn(trace, points, state):
print(points.point_inds)
fig.data[0].on_click(click_fn)Registers a handler that receives the clicked trace, selected-point information, and input-device state.
When to use it
Interactive notebook responses
Update trace styling or related notebook state after a click.
Composed event handlers
Install more than one independent click handler on the same trace.
Interview questions
QWhat arguments does the click callback receive?
The callback is a callable accepting three arguments: the trace, a plotly.callbacks.Points object, and a plotly.callbacks.InputDeviceState object. The Points object can provide the indices of clicked points.
Follow-up: How would you preserve an existing handler? Pass append=True when registering the new callback.
QHow do you register and activate a point-click callback?
Register the function with the trace’s on_click method, for example trace.on_click(click_fn). The trace must be displayed through a FigureWidget in an ipywidget context.
Follow-up: Would the same handler fire for a figure shown with plot or iplot? No, the page says those display paths do not trigger callbacks.
QWhat does the append argument control?
By default, a new callback replaces previously defined on_click callbacks for that trace. Passing append=True adds the callback to the existing list instead.
Follow-up: What is the practical consequence of omitting append when composing handlers? Earlier handlers are removed for that trace.
Related
plotly.graph_objects.FigureWidgetplotly.callbacks.Pointsplotly.callbacks.InputDeviceStateon_hoveron_selection