Plotly · Module

fig.add_shape

Adds a standalone geometric shape—such as a line, ellipse, rectangle, or path—to a Plotly figure. Its coordinates can be tied to subplot axes or positioned relative to the figure.

How it works

Call add_shape on a Figure to append a standalone line, rectangle, ellipse, or polygon-like path to the layout. Coordinates can be interpreted against plot axes or positioned using absolute figure references such as paper or domain coordinates, and styling is supplied through shape properties.

Syntax

fig.add_shape(type=None, x0=None, x1=None, y0=None, y1=None, xref=None, yref=None, row='all', col='all', exclude_empty_subplots=True, **kwargs)

Parameters

Name	Type	Description
`**kwargs`	`named shape properties`	Shape properties such as `type`, coordinates, axis references, line styling, fill, opacity, labels, and legend settings.

Returns

The updated Figure object, allowing method chaining.

Key points

Use fig.add_shape() to add standalone lines, ellipses, and rectangles to a figure.
Absolute positioning lets a shape be placed independently of the plotted data.
Axis-relative positioning makes shape coordinates follow the data coordinates of a 2D Cartesian subplot.
Use arrays for xref and yref when a shape should span multiple subplots.

Common mistakes

Choose xref and yref deliberately: shapes may use absolute figure placement or 2D axis data coordinates.

Example: Add a rectangle shape

import plotly.graph_objects as go

fig = go.Figure()
fig.add_shape(
    type="rect",
    x0=1,
    x1=3,
    y0=2,
    y1=4,
    line=dict(color="RoyalBlue"),
    fillcolor="LightSkyBlue",
)
fig.show()

Creates a rectangle in data coordinates on a Plotly figure.

When to use it

Emphasize data intervals

Highlight a range or region in a chart

Add reference lines

Mark a threshold or target value

Annotate images or plotted objects

Draw bounding boxes around visual features

Overlay multi-subplot shapes

Add custom geometric overlays across subplot layouts

Interview questions

QWhat does fig.add_shape() do?

add_shape adds a standalone geometric shape to a figure. Typical shapes include lines, rectangles, and ellipses; coordinates and references determine where the shape is drawn.

Follow-up: How can one shape span multiple subplots? Pass arrays of axis references to xref and yref, as supported by the shapes documentation.

QHow are shape positions controlled?

Shape coordinates are interpreted through reference properties such as xref and yref. Using axis references places the shape in data coordinates, while paper or domain references support figure-relative placement.

Follow-up: How would you add a horizontal target line? Use a line shape with matching y0 and y1, and select suitable x and y references.

QHow do shapes participate in legends?

A shape can be shown in the legend by setting showlegend=True; otherwise its legend item is disabled by default. The shape can also receive a name for the legend entry.

Follow-up: What should be configured when users need to toggle a shape from the legend? Set showlegend=True and provide an appropriate shape name.

Figure.add_hline
Figure.add_vline
Figure.add_hrect
Figure.add_vrect
Figure.add_annotation
layout.shapes
layout.newshape

Source: Shapes in Python - Plotly. Checked 2026-10-15.