Plotly · Module

fig.add_annotation

Adds a standalone text annotation to a Plotly figure, optionally with an arrow. Coordinates can refer to subplot axes, the figure’s paper space, or an axis domain.

How it works

Call fig.add_annotation() on a Plotly figure to append one standalone text annotation. Its coordinates default to the plot axes, while xref and yref can switch either coordinate to paper space or an axis domain; arrow and text options control the callout’s appearance.

Syntax

fig.add_annotation(arg=None, x=None, y=None, xref=None, yref=None, text=None, showarrow=None, arrowhead=None, ax=None, ay=None, **kwargs)

Key points

The method appends a single standalone text label, optionally rendered with an arrow.
Paper coordinates provide absolute placement within the complete figure.
Annotations can target axes on both two-dimensional and three-dimensional Cartesian subplots.
Without explicit references, the x and y values use the plot axes.
Arrow text coordinates and dimensions may be set explicitly when they share the arrowhead’s coordinate system.

Common mistakes

Coordinates follow the plot axes by default, so an annotation moves when the plot is panned.
Use paper coordinates for placement relative to the whole figure rather than the data axes.
Use an axis reference followed by domain when positioning relative to an axis’s normalized domain.

Example: Add a data-coordinate annotation

import plotly.express as px

fig = px.scatter(x=[1, 2, 3], y=[2, 4, 3])
fig.add_annotation(
    x=2,
    y=4,
    text="Peak",
    showarrow=True,
    arrowhead=2,
)
fig.show()

Adds a labeled callout at the data point (2, 4), with an arrow pointing to it.

When to use it

Data-point callouts

Call out a notable point on a scatter or line chart with explanatory text and an arrow.

Figure-level labels

Place a fixed caption, label, or control hint at a precise location in the overall figure.

Subplot annotations

Annotate values or features in a 2D or 3D Cartesian subplot using the subplot’s coordinate system.

Interview questions

QWhat does fig.add_annotation() do?

It adds a standalone text annotation to an existing figure. The annotation can include an arrow and can use either axis-relative or figure-relative coordinates.

Follow-up: How would you make it stay at a fixed location while panning? Set xref and yref to "paper" and provide paper coordinates.

QWhat coordinate system is used by default?

The default references are xref="x" and yref="y", so x and y are interpreted in the subplot’s data coordinates. This makes the annotation track the plotted data during navigation.

Follow-up: How can placement be relative to an axis domain? Add domain to the relevant axis reference, such as xref="x domain".

QHow do you create an arrowed callout?

Set showarrow=True and configure arrow properties such as arrowhead; provide ax and ay when specifying the arrow’s tail. The arrow dimensions must use the same coordinate system as the arrowhead.

Follow-up: What alternative is available for a simple label without a callout? Set showarrow=False and position the text directly.

fig.update_layout
layout.annotations
layout.annotation

Source: Text and Annotations in Python - Plotly. Checked 2026-10-15.