PlotlyWidget.add_trace(trace, row=None, col=None, secondary_y=None, exclude_empty_subplots=False)

Add a trace to the figure

  • trace (BaseTraceType or dict) –

    • An instances of a trace classe from the plotly.graph_objs package (e.g plotly.graph_objs.Scatter, plotly.graph_objs.Bar)

    • or a dicts where:

      • The ‘type’ property specifies the trace type (e.g. ‘scatter’, ‘bar’, ‘area’, etc.). If the dict has no ‘type’ property then ‘scatter’ is assumed.

      • All remaining properties are passed to the constructor of the specified trace type.

  • row ('all', int or None (default)) – Subplot row index (starting from 1) for the trace to be added. Only valid if figure was created using If ‘all’, addresses all rows in the specified column(s).

  • col ('all', int or None (default)) – Subplot col index (starting from 1) for the trace to be added. Only valid if figure was created using If ‘all’, addresses all columns in the specified row(s).

  • secondary_y (boolean or None (default None)) –

    If True, associate this trace with the secondary y-axis of the subplot at the specified row and col. Only valid if all of the following conditions are satisfied:

    • The figure was created using plotly.subplots.make_subplots.

    • The row and col arguments are not None

    • The subplot at the specified row and col has type xy (which is the default) and secondary_y True. These properties are specified in the specs argument to make_subplots. See the make_subplots docstring for more info.

    • The trace argument is a 2D cartesian trace (scatter, bar, etc.)

  • exclude_empty_subplots (boolean) – If True, the trace will not be added to subplots that don’t already have traces.


The Figure that add_trace was called on

Return type



>>> from plotly import subplots
>>> import plotly.graph_objs as go

Add two Scatter traces to a figure

>>> fig = go.Figure()
>>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2])) 
>>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2])) 

Add two Scatter traces to vertically stacked subplots

>>> fig = subplots.make_subplots(rows=2)
>>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=1, col=1) 
>>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=2, col=1)