Plotly · Module

fig.add_scatter

Adds a scatter trace to a Plotly figure, with support for x/y data, rendering modes, labels, styling, and subplot placement. It returns the updated figure for continued construction or display.

How it works

fig.add_scatter creates a Scatter trace from keyword arguments and appends it to the figure. Trace properties such as coordinates, rendering mode, labels, styling, and subplot placement can be supplied directly; the method returns the figure so calls can be chained.

Syntax

fig.add_scatter(row=None, col=None, secondary_y=None, **kwargs)

Parameters

Name	Type	Description
`kwargs`	`dict`	Scatter trace properties, including data, display mode, labels, styling, and axis-related settings.
`row`	`int`	Subplot row in which to place the trace.
`col`	`int`	Subplot column in which to place the trace.
`secondary_y`	`bool`	Whether the trace uses the subplot's secondary y-axis when supported by the layout.

Returns

The updated Figure object.

Key points

The method accepts trace data together with subplot placement arguments, allowing a scatter trace to be inserted directly into a selected subplot.
Scatter-family traces support text labels, so use the text attribute when each point needs associated annotation content.
Use line mode when the trace represents a connected path, such as a trend, boundary, or polygon edge.
Closed scatter-based shapes can use a self-fill setting to color the region enclosed by the trace.

Common mistakes

For subplot figures, use the appropriate row and col coordinates; the target cell must exist in the figure's subplot layout.

Example: Add an interactive scatter trace

import plotly.graph_objects as go

fig = go.Figure()
fig.add_scatter(
    x=[1, 2, 3],
    y=[2, 5, 3],
    mode="lines+markers",
    name="Series A",
)
fig.show()

Creates a figure, adds a scatter trace with x/y data and combined lines and markers, then displays the interactive chart.

When to use it

Trend and relationship plots

Plot measured or modeled values against an x-axis with points, connecting lines, or both.

Multi-series figures

Build a chart incrementally by appending multiple independent scatter series.

Subplot dashboards

Place traces into cells of a figure created with Plotly's subplot utilities.

Area and envelope charts

Create filled regions or stacked area visualizations from scatter traces.

Interview questions

QWhat does fig.add_scatter do?

fig.add_scatter adds a go.Scatter trace to an existing go.Figure. It is convenient when constructing a figure incrementally because scatter attributes can be passed as keyword arguments.

Follow-up: How would you add two independent series? Call add_scatter twice, supplying distinct x/y data and names; Plotly renders each call as its own trace.

QHow do you control scatter rendering?

The mode attribute controls whether the scatter trace displays markers, lines, text, or combinations of them. For example, mode="lines+markers" renders both connecting lines and points.

Follow-up: How can an area be filled? Use a scatter trace's fill setting, such as fill="tozeroy" or fill="tonexty", and choose mode="none" when markers and lines are unnecessary.

QHow is a scatter trace placed in a subplot?

A scatter trace can be positioned in a subplot by passing row and col to the add method. This places the trace in the selected subplot cell rather than the default location.

Follow-up: How can a trace use a secondary y-axis? In a subplot configured with secondary axes, pass the relevant secondary-axis option when adding the trace.

go.Scatter
fig.add_trace
fig.add_traces
fig.update_traces

Source: plotly package — 7.0.0 documentation. Checked 2026-10-15.